diff --git a/.Rbuildignore b/.Rbuildignore index 1ed837b655c74b7fbca27c426fe5a18b9f4c620b..ba637f5203b039844510c72b6723061599defdd5 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -5,6 +5,7 @@ ./.nc$ .*^(?!data)\.RData$ .*\.gitlab-ci.yml$ -#^tests$ +^tests$ ./.nfs* ^cran-comments\.md$ +./vignettes/*.md diff --git a/DESCRIPTION b/DESCRIPTION index 28a2634ba0bf876f2f9b062e01d84238e7e08d81..d85555958676c8a89b5215256862c87e1fdc5cb0 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,15 +1,28 @@ Package: CSIndicators Title: Climate Services' Indicators Based on Sub-Seasonal to Decadal Predictions -Version: 0.0.1 +Version: 0.0.2 Authors@R: c( - person("Nuria", "Perez-Zanon", , "nuria.perez@bsc.es", role = c("aut", "cre"), comment = c(ORCID = "0000-0001-8568-3071")), + person("Eva", "Rifà", , "eva.rifarovira@bsc.es", role = c("cre")), + person("Nuria", "Perez-Zanon", , "nuria.perez@bsc.es", role = c("aut"), comment = c(ORCID = "0000-0001-8568-3071")), person("Chou", "Chihchung", ,"chihchung.chou@bsc.es", role = "aut"), person("Llorenç", "Lledó", , "llorenc.lledo@bsc.es", role = "aut"), person("González-Reviriego", "Nube", , "nube.gonzalez@bsc.es", role = "ctb"), person("Marcos", "Raül", , "raul.marcos@bsc.es", role = "ctb"), person("Palma", "Lluis", , "lluis.palma@bsc.es", role = "ctb"), + person("An-Chi", "Ho", , "an.ho@bsc.es", role = c("ctb")), person("BSC-CNS", role = "cph")) -Description: Set of generalised tools for the flexible computation of climate related indicators defined by the user. Each method represents a specific mathematical approach which is combined with the possibility to select an arbitrary time period to define the indicator. This enables a wide range of possibilities to tailor the most suitable indicator for each particular climate service application (agriculture, food security, energy, water management…). This package is intended for sub-seasonal, seasonal and decadal climate predictions, but its methods are also applicable to other time-scales, provided the dimensional structure of the input is maintained. Additionally, the outputs of the functions in this package are compatible with 'CSTools'. This package was developed in the context of H2020 MED-GOLD (776467) and S2S4E (776787) projects. Lledó et al. (2019) . +Description: Set of generalised tools for the flexible computation of climate + related indicators defined by the user. Each method represents a specific + mathematical approach which is combined with the possibility to select an + arbitrary time period to define the indicator. This enables a wide range of + possibilities to tailor the most suitable indicator for each particular climate + service application (agriculture, food security, energy, water management…). + This package is intended for sub-seasonal, seasonal and decadal climate + predictions, but its methods are also applicable to other time-scales, + provided the dimensional structure of the input is maintained. Additionally, + the outputs of the functions in this package are compatible with 'CSTools'. + This package was developed in the context of H2020 MED-GOLD (776467) and + S2S4E (776787) projects. Lledó et al. (2019) . Depends: R (>= 3.6.0) Imports: @@ -28,4 +41,4 @@ License: Apache License 2.0 URL: https://earth.bsc.es/gitlab/es/csindicators/ BugReports: https://earth.bsc.es/gitlab/es/csindicators/-/issues Encoding: UTF-8 -RoxygenNote: 7.0.1 +RoxygenNote: 7.2.0 diff --git a/NEWS.md b/NEWS.md new file mode 100644 index 0000000000000000000000000000000000000000..fa2bb871d026192b20e4a2731df33061c5d83b59 --- /dev/null +++ b/NEWS.md @@ -0,0 +1,7 @@ +# CSIndicators 0.0.2 (Release date: 2022-10-21) +- Correct figures of EnergyIndicators vignette. +- Sanity check correction in functions CST_PeriodAccumulation, CST_AbsToProbs, CST_AccumulationExceedingThreshold, CST_MergeRefToExp, CST_PeriodMean, CST_QThreshold, CST_SelectPeriodOnData, CST_Threshold, TotalSpellTimeExceedingThreshold, CST_TotalTimeExceedingThreshold, CST_WindCapacityFactor and CST_WindPowerDensity. +- Revise examples using s2dv::InsertDim in MergeRefToExp(). + +# CSIndicators 0.0.1 (Release date: 2021-05-07) +- This package is intended for sub-seasonal, seasonal and decadal climate predictions, but its methods are also applicable to other time-scales. Additionally, the outputs of the functions in this package are compatible with 'CSTools'. This package was developed in the context of H2020 MED-GOLD (776467) and S2S4E (776787) projects. Lledó et al. (2019) . \ No newline at end of file diff --git a/R/AbsToProbs.R b/R/AbsToProbs.R index af7b616228489146a171cfc56615102effddea4a..708fabdafbec4e9cbf094fb53c586741a48b52f6 100644 --- a/R/AbsToProbs.R +++ b/R/AbsToProbs.R @@ -1,32 +1,53 @@ #'Transform ensemble forecast into probabilities #' -#'The Cumulative Distribution Function of a forecast is used to obtain the probabilities of each value in the ensemble. If multiple initializations (start dates) are provided, the function will create the Cumulative Distribution Function excluding the corresponding initialization. +#'The Cumulative Distribution Function of a forecast is used to obtain the +#'probabilities of each value in the ensemble. If multiple initializations +#'(start dates) are provided, the function will create the Cumulative +#'Distribution Function excluding the corresponding initialization. #' -#'@param data an 's2dv_cube' object as provided function \code{CST_Load} in package CSTools. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the temporal dimension. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. This dimension is required to subset the data in a requested period. -#'@param memb_dim a character string indicating the name of the dimension in which the ensemble members are stored. -#'@param sdate_dim a character string indicating the name of the dimension in which the initialization dates are stored. -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data An 's2dv_cube' object as provided function \code{CST_Load} in +#' package CSTools. +#'@param start An optional parameter to define the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to define the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the temporal +#' dimension. By default, it is set to 'ftime'. More than one dimension name +#' matching the dimensions provided in the object \code{data$data} can be +#' specified. This dimension is required to subset the data in a requested +#' period. +#'@param memb_dim A character string indicating the name of the dimension in +#' which the ensemble members are stored. +#'@param sdate_dim A character string indicating the name of the dimension in +#' which the initialization dates are stored. +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A 's2dv_cube' object containing the probabilites in the element \code{data}. -#' -#'@import multiApply -#'@importFrom stats ecdf +#'@return An 's2dv_cube' object containing the probabilites in the element \code{data}. #' #'@examples -#'exp <- CSTools::lonlat_prec +#'exp <- NULL +#'exp$data <- array(rnorm(216), dim = c(dataset = 1, member = 2, sdate = 3, +#' ftime = 9, lat = 2, lon = 2)) +#'class(exp) <- 's2dv_cube' #'exp_probs <- CST_AbsToProbs(exp) #'exp$data <- array(rnorm(5 * 3 * 214 * 2), -#' c(member = 5, sdate = 3, ftime = 214, lon = 2)) +#' c(member = 5, sdate = 3, ftime = 214, lon = 2)) #'exp$Dates[[1]] <- c(seq(as.Date("01-05-2000", format = "%d-%m-%Y"), -#' as.Date("30-11-2000", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), -#' as.Date("30-11-2001", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), -#' as.Date("30-11-2002", format = "%d-%m-%Y"), by = 'day')) +#' as.Date("30-11-2000", format = "%d-%m-%Y"), by = 'day'), +#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), +#' as.Date("30-11-2001", format = "%d-%m-%Y"), by = 'day'), +#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), +#' as.Date("30-11-2002", format = "%d-%m-%Y"), by = 'day')) #'exp_probs <- CST_AbsToProbs(exp, start = list(21, 4), end = list(21, 6)) +#' +#'@import multiApply +#'@importFrom stats ecdf #'@export CST_AbsToProbs <- function(data, start = NULL, end = NULL, time_dim = 'ftime', memb_dim = 'member', @@ -40,13 +61,13 @@ CST_AbsToProbs <- function(data, start = NULL, end = NULL, if (is.null(dim(data$Dates$start))) { if (length(data$Dates$start) != dim(data$data)[time_dim]) { if (length(data$Dates$start) == - prod(dim(data$data)[time_dim] * dim(data$data)['sdate'])) { + prod(dim(data$data)[time_dim] * dim(data$data)[sdate_dim])) { dim(data$Dates$start) <- c(dim(data$data)[time_dim], - dim(data$data)['sdate']) + dim(data$data)[sdate_dim]) + } else { + warning("Dimensions in 'data' element 'Dates$start' are missed and ", + "all data would be used.") } - } else { - warning("Dimensions in 'data' element 'Dates$start' are missed and", - "all data would be used.") } } } @@ -63,34 +84,54 @@ CST_AbsToProbs <- function(data, start = NULL, end = NULL, } #'Transform ensemble forecast into probabilities #' -#'The Cumulative Distribution Function of a forecast is used to obtain the probabilities of each value in the ensemble. If multiple initializations (start dates) are provided, the function will create the Cumulative Distribution Function excluding the corresponding initialization. +#'The Cumulative Distribution Function of a forecast is used to obtain the +#'probabilities of each value in the ensemble. If multiple initializations +#'(start dates) are provided, the function will create the Cumulative +#'Distribution Function excluding the corresponding initialization. #' -#'@param data a multidimensional array with named dimensions. -#'@param dates a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the temporal dimension. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. This dimension is required to subset the data in a requested period. -#'@param memb_dim a character string indicating the name of the dimension in which the ensemble members are stored. -#'@param sdate_dim a character string indicating the name of the dimension in which the initialization dates are stored. -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data A multidimensional array with named dimensions. +#'@param dates A vector of dates or a multidimensional array of dates with named +#' dimensions matching the dimensions on parameter 'data'. By default it is +#' NULL, to select a period this parameter must be provided. +#'@param start An optional parameter to define the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to define the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the temporal +#' dimension. By default, it is set to 'ftime'. More than one dimension name +#' matching the dimensions provided in the object \code{data$data} can be +#' specified. This dimension is required to subset the data in a requested +#' period. +#'@param memb_dim A character string indicating the name of the dimension in +#' which the ensemble members are stored. +#'@param sdate_dim A character string indicating the name of the dimension in +#' which the initialization dates are stored. +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A multidimensional array with named dimensions. -#' -#'@import multiApply -#'@importFrom stats ecdf +#'@return A multidimensional array with named dimensions containing the +#'probabilites in the element \code{data}. #' #'@examples -#'exp <- CSTools::lonlat_prec$data +#'exp <- array(rnorm(216), dim = c(dataset = 1, member = 2, sdate = 3, ftime = 9, lat = 2, lon = 2)) #'exp_probs <- AbsToProbs(exp) #'data <- array(rnorm(5 * 2 * 61 * 1), -#' c(member = 5, sdate = 2, ftime = 61, lon = 1)) +#' c(member = 5, sdate = 2, ftime = 61, lon = 1)) #'Dates <- c(seq(as.Date("01-05-2000", format = "%d-%m-%Y"), -#' as.Date("30-06-2000", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), -#' as.Date("30-06-2001", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), -#' as.Date("30-06-2002", format = "%d-%m-%Y"), by = 'day')) +#' as.Date("30-06-2000", format = "%d-%m-%Y"), by = 'day'), +#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), +#' as.Date("30-06-2001", format = "%d-%m-%Y"), by = 'day'), +#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), +#' as.Date("30-06-2002", format = "%d-%m-%Y"), by = 'day')) #'exp_probs <- AbsToProbs(exp, start = list(21, 4), end = list(21, 6)) +#' +#'@import multiApply +#'@importFrom stats ecdf #'@export AbsToProbs <- function(data, dates = NULL, start = NULL, end = NULL, time_dim = 'time', memb_dim = 'member', diff --git a/R/AccumulationExceedingThreshold.R b/R/AccumulationExceedingThreshold.R index e953d32c5f781f6eb2dbe17e717593aa25439d0e..f202dca791a07a96d523e8b5680f80159138b00e 100644 --- a/R/AccumulationExceedingThreshold.R +++ b/R/AccumulationExceedingThreshold.R @@ -1,35 +1,59 @@ #'Accumulation of a variable when Exceeding (not exceeding) a Threshold #' -#'The accumulation (sum) of a variable in the days (or time steps) that the variable is exceeding (or not exceeding) a threshold during a period. The threshold provided must be -#'in the same units than the variable units, i.e. to use a percentile as a scalar, -#'the function \code{Threshold} or \code{QThreshold} may be needed. -#'Providing mean daily temperature data, the following agriculture indices for heat stress can be obtained by using this function: +#'The accumulation (sum) of a variable in the days (or time steps) that the +#'variable is exceeding (or not exceeding) a threshold during a period. The +#'threshold provided must be in the same units than the variable units, i.e. to +#'use a percentile as a scalar, the function \code{Threshold} or +#'\code{QThreshold} may be needed. Providing mean daily temperature data, the +#'following agriculture indices for heat stress can be obtained by using this +#'function: #'\itemize{ -#' \item\code{GDD}{Summation of daily differences between daily average temperatures and 10°C between April 1st and October 31st}} +#' \item\code{GDD}{Summation of daily differences between daily average +#' temperatures and 10°C between April 1st and October 31st} +#'} #' -#'@param data a 's2dv_cube' object as provided by function \code{CST_Load} in package CSTools. -#'@param threshold a 's2dv_cube' object as output of a 'CST_' function in the same units as parameter 'data' and with the common dimensions of the element 'data' of the same length. A single scalar is also possible. -#'@param op a opartor '>' (by default), '<', '>=' or '<='. -#'@param diff a logical value indicating whether to accumulate the difference between data and threshold (TRUE) or not (FALSE by default). -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param na.rm a logical value indicating whether to ignore NA values (TRUE) or not (FALSE). -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data An 's2dv_cube' object as provided by function \code{CST_Load} in +#' package CSTools. +#'@param threshold An 's2dv_cube' object as output of a 'CST_' function in the +#' same units as parameter 'data' and with the common dimensions of the element +#' 'data' of the same length. A single scalar is also possible. +#'@param op An operator '>' (by default), '<', '>=' or '<='. +#'@param diff A logical value indicating whether to accumulate the difference +#' between data and threshold (TRUE) or not (FALSE by default). +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the dimension to +#' compute the indicator. By default, it is set to 'ftime'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param na.rm A logical value indicating whether to ignore NA values (TRUE) or +#' not (FALSE). +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' #'@return A 's2dv_cube' object containing the indicator in the element \code{data}. #' -#'@import multiApply #'@examples -#'exp <- CSTools::lonlat_data$exp -#'exp$data <- CSTools::lonlat_data$exp$data[1, 5, 3, 3, 1, 1] +#'exp <- NULL +#'exp$data <- array(rnorm(216)*200, dim = c(dataset = 1, member = 2, sdate = 3, +#' ftime = 9, lat = 2, lon = 2)) +#'class(exp) <- 's2dv_cube' #'DOT <- CST_AccumulationExceedingThreshold(exp, threshold = 280) +#' +#'@import multiApply #'@export CST_AccumulationExceedingThreshold <- function(data, threshold, op = '>', - diff = FALSE, - start = NULL, end = NULL, - time_dim = 'ftime', - na.rm = FALSE, ncores = NULL) { + diff = FALSE, + start = NULL, end = NULL, + time_dim = 'ftime', + na.rm = FALSE, ncores = NULL) { if (!inherits(data, 's2dv_cube')) { stop("Parameter 'data' must be of the class 's2dv_cube', ", "as output by CSTools::CST_Load.") @@ -38,24 +62,24 @@ CST_AccumulationExceedingThreshold <- function(data, threshold, op = '>', if (!is.null(start) && !is.null(end)) { if (is.null(dim(data$Dates$start))) { if (length(data$Dates$start) != dim(data$data)[time_dim]) { - if (length(data$Dates$start) == + if (length(data$Dates$start) == prod(dim(data$data)[time_dim] * dim(data$data)['sdate'])) { dim(data$Dates$start) <- c(dim(data$data)[time_dim], dim(data$data)['sdate']) + } else { + warning("Dimensions in 'data' element 'Dates$start' are missed and ", + "all data would be used.") } - } else { - warning("Dimensions in 'data' element 'Dates$start' are missed and", - "all data would be used.") } } - } + } if (inherits(threshold, 's2dv_cube')) { threshold <- threshold$data } total <- AccumulationExceedingThreshold(data$data, data$Dates[[1]], - threshold = threshold, op = op, diff = diff, - start = start, end = end, time_dim = time_dim, - na.rm = na.rm, ncores = ncores) + threshold = threshold, op = op, diff = diff, + start = start, end = end, time_dim = time_dim, + na.rm = na.rm, ncores = ncores) data$data <- total if (!is.null(start) && !is.null(end)) { data$Dates <- SelectPeriodOnDates(dates = data$Dates$start, @@ -66,25 +90,48 @@ CST_AccumulationExceedingThreshold <- function(data, threshold, op = '>', } #'Accumulation of a variable when Exceeding (not exceeding) a Threshold #' -#'The accumulation (sum) of a variable in the days (or time steps) that the variable is exceeding (or not exceeding) a threshold during a period. The threshold provided must be -#'in the same units than the variable units, i.e. to use a percentile as a scalar, -#'the function \code{Threshold} or \code{QThreshold} may be needed. -#'Providing mean daily temperature data, the following agriculture indices for heat stress can be obtained by using this function: +#'The accumulation (sum) of a variable in the days (or time steps) that the +#'variable is exceeding (or not exceeding) a threshold during a period. The +#'threshold provided must be in the same units than the variable units, i.e. to +#'use a percentile as a scalar, the function \code{Threshold} or +#'\code{QThreshold} may be needed. Providing mean daily temperature data, the +#'following agriculture indices for heat stress can be obtained by using this +#'function: #'\itemize{ -#' \item\code{GDD}{Summation of daily differences between daily average temperatures and 10°C between April 1st and October 31st}} +#' \item\code{GDD}{Summation of daily differences between daily average +#' temperatures and 10°C between April 1st and October 31st} +#'} #' -#'@param data a multidimensional array with named dimensions. -#'@param threshold a multidimensional array with named dimensions in the same units as parameter 'data' and with the common dimensions of the element 'data' of the same length. -#'@param op a opartor '>' (by default), '<', '>=' or '<='. -#'@param diff a logical value indicating whether to accumulate the difference between data and threshold (TRUE) or not (FALSE by default). -#'@param dates a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param na.rm a logical value indicating whether to ignore NA values (TRUE) or not (FALSE). -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data A multidimensional array with named dimensions. +#'@param threshold a multidimensional array with named dimensions in the same +#' units as parameter 'data' and with the common dimensions of the element +#' 'data' of the same length. +#'@param op An operator '>' (by default), '<', '>=' or '<='. +#'@param diff A logical value indicating whether to accumulate the difference +#' between data and threshold (TRUE) or not (FALSE by default). +#'@param dates A vector of dates or a multidimensional array of dates with named +#' dimensions matching the dimensions on parameter 'data'. By default it is +#' NULL, to select a period this parameter must be provided. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the dimension to +#' compute the indicator. By default, it is set to 'ftime'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param na.rm A logical value indicating whether to ignore NA values (TRUE) or +#' not (FALSE). +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A multidimensional array with named dimensions. +#'@return A multidimensional array with named dimensions containing the +#'indicator in the element \code{data}. #' #'@import multiApply #'@examples @@ -101,10 +148,10 @@ CST_AccumulationExceedingThreshold <- function(data, threshold, op = '>', #' end = list(31, 10)) #'@export AccumulationExceedingThreshold <- function(data, threshold, op = '>', - diff = FALSE, - dates = NULL, start = NULL, end = NULL, - time_dim = 'time', na.rm = FALSE, - ncores = NULL) { + diff = FALSE, + dates = NULL, start = NULL, end = NULL, + time_dim = 'time', na.rm = FALSE, + ncores = NULL) { if (is.null(data)) { stop("Parameter 'data' cannot be NULL.") } @@ -116,7 +163,7 @@ AccumulationExceedingThreshold <- function(data, threshold, op = '>', names(dim(data)) <- time_dim } if (is.null(threshold)) { - stop("Parameter 'threshold' cannot be NULL.") + stop("Parameter 'threshold' cannot be NULL.") } if (!is.numeric(threshold)) { stop("Parameter 'threshold' must be numeric.") @@ -142,7 +189,7 @@ AccumulationExceedingThreshold <- function(data, threshold, op = '>', if (all(time_dim %in% names(dim(threshold)))) { if (dim(threshold)[time_dim] == dim(data)[time_dim]) { threshold <- SelectPeriodOnData(threshold, dates, start, end, - time_dim = time_dim, ncores = ncores) + time_dim = time_dim, ncores = ncores) } } data <- SelectPeriodOnData(data, dates, start, end, @@ -181,9 +228,6 @@ AccumulationExceedingThreshold <- function(data, threshold, op = '>', return(total) } -#x <- 1:10 -#y <- 3 -#.sumexceedthreshold(x, y, '>', T) .sumexceedthreshold <- function(x, y, op, na.rm) { if (op == '>') { res <- sum(x[x > y], na.rm = na.rm) diff --git a/R/MergeRefToExp.R b/R/MergeRefToExp.R index 365ceb51178df6135dce1ea09956d7b4f1a0f1d8..216dc8e831a8448909a7f1e2284519e216e660e2 100644 --- a/R/MergeRefToExp.R +++ b/R/MergeRefToExp.R @@ -1,20 +1,42 @@ #'Merge a Reference To Experiments #' -#'Some indicators are defined for specific temporal periods (e.g.: summer from June 21st to September 21st). If the initialization forecast date is later than the one required for the indicator (e.g.: July 1st), the user may want to merge past observations, or other references, to the forecast (or hindcast) to compute the indicator. The function \code{MergeObs2Exp} takes care of this steps. If the forecast simulation doesn't cover the required period because it is initialized too early (e.g.: Initialization on November 1st the forecast covers until the beginning of June next year), a climatology (or other references) could be added at the end of the forecast lead time to cover the desired period (e.g.: until the end of summer). +#'Some indicators are defined for specific temporal periods (e.g.: summer from +#'June 21st to September 21st). If the initialization forecast date is later +#'than the one required for the indicator (e.g.: July 1st), the user may want to +#'merge past observations, or other references, to the forecast (or hindcast) +#'to compute the indicator. The function \code{MergeObs2Exp} takes care of this +#'steps. If the forecast simulation doesn't cover the required period because it +#'is initialized too early (e.g.: Initialization on November 1st the forecast +#'covers until the beginning of June next year), a climatology (or other +#'references) could be added at the end of the forecast lead time to cover the +#'desired period (e.g.: until the end of summer). #' -#'@param data1 an 's2dv_cube' object as provided function \code{CST_Load} in package CSTools. -#'@param data2 an 's2dv_cube' object as provided function \code{CST_Load} in package CSTools. -#'@param start1 a list to defined the initial date of the period to select from data1 by providing a list of two elements: the initial date of the period and the initial month of the period. -#'@param end1 a list to defined the final date of the period to select from data1 by providing a list of two elements: the final day of the period and the final month of the period. -#'@param start2 a list to defined the initial date of the period to select from data2 by providing a list of two elements: the initial date of the period and the initial month of the period. -#'@param end2 a list to defined the final date of the period to select from data2 by providing a list of two elements: the final day of the period and the final month of the period. -#'@param time_dim a character string indicating the name of the temporal dimension. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. This dimension is required to subset the data in a requested period. -#'@param sdate_dim a character string indicating the name of the dimension in which the initialization dates are stored. -#'@param ncores an integer indicating the number of cores to use in parallel computation. -#'@return A 's2dv_cube' object containing the indicator in the element \code{data}. -#' -#'@import multiApply -#'@importFrom ClimProjDiags Subset +#'@param data1 An 's2dv_cube' object as provided function \code{CST_Load} in +#' package CSTools. +#'@param data2 An 's2dv_cube' object as provided function \code{CST_Load} in +#' package CSTools. +#'@param start1 A list to define the initial date of the period to select from +#' data1 by providing a list of two elements: the initial date of the period +#' and the initial month of the period. +#'@param end1 A list to define the final date of the period to select from +#' data1 by providing a list of two elements: the final day of the period and +#' the final month of the period. +#'@param start2 A list to define the initial date of the period to select from +#' data2 by providing a list of two elements: the initial date of the period +#' and the initial month of the period. +#'@param end2 A list to define the final date of the period to select from +#' data2 by providing a list of two elements: the final day of the period and +#' the final month of the period. +#'@param time_dim A character string indicating the name of the temporal +#' dimension. By default, it is set to 'ftime'. More than one dimension name +#' matching the dimensions provided in the object \code{data$data} can be +#' specified. This dimension is required to subset the data in a requested period. +#'@param sdate_dim A character string indicating the name of the dimension in +#' which the initialization dates are stored. +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. +#'@return A 's2dv_cube' object containing the indicator in the element +#' \code{data}. #' #'@examples #'data_dates <- c(seq(as.Date("01-07-1993", "%d-%m-%Y", tz = 'UTC'), @@ -22,18 +44,23 @@ #' seq(as.Date("01-07-1994", "%d-%m-%Y", tz = 'UTC'), #' as.Date("01-12-1994","%d-%m-%Y", tz = 'UTC'), "day")) #'dim(data_dates) <- c(ftime = 154, sdate = 2) +#'data <- NULL +#'data$data <- array(1:(2*154*2), c(ftime = 154, sdate = 2, member= 2)) +#'data$Dates$start <- data_dates +#'class(data) <- 's2dv_cube' #'ref_dates <- seq(as.Date("01-01-1993", "%d-%m-%Y", tz = 'UTC'), #' as.Date("01-12-1994","%d-%m-%Y", tz = 'UTC'), "day") #'dim(ref_dates) <- c(ftime = 350, sdate = 2) -#'ref <- array(1001:1700, c(ftime = 350, sdate = 2)) -#'data <- array(1:(2*154*2), c(ftime = 154, sdate = 2, member= 2)) -#'ref <- CSTools::s2dv_cube(data = ref, Dates = list(start = ref_dates, -#' end = ref_dates)) -#'data <- CSTools::s2dv_cube(data = data, Dates = list(start = data_dates, -#' end = data_dates)) +#'ref <- NULL +#'ref$data <- array(1001:1700, c(ftime = 350, sdate = 2)) +#'ref$Dates$start <- ref_dates +#'class(ref) <- 's2dv_cube' #'new_data <- CST_MergeRefToExp(data1 = ref, data2 = data, #' start1 = list(21, 6), end1 = list(30, 6), #' start2 = list(1, 7), end2 = list(21, 9)) +#' +#'@import multiApply +#'@importFrom ClimProjDiags Subset #'@export CST_MergeRefToExp <- function(data1, data2, start1, end1, start2, end2, time_dim = 'ftime', sdate_dim = 'sdate', @@ -52,11 +79,11 @@ CST_MergeRefToExp <- function(data1, data2, start1, end1, start2, end2, if (length(data1$Dates$start) == prod(dim(data1$data)[time_dim] * dim(data1$data)['sdate'])) { dim(data1$Dates$start) <- c(dim(data1$data)[time_dim], - dim(data1$data)['sdate']) + dim(data1$data)['sdate']) + } else { + warning("Dimensions in 'data' element 'data$Dates$start' are missed and", + "all data would be used.") } - } else { - warning("Dimensions in 'data' element 'data$Dates$start' are missed and", - "all data would be used.") } } # when subsetting is needed, dimensions are also needed: @@ -66,27 +93,27 @@ CST_MergeRefToExp <- function(data1, data2, start1, end1, start2, end2, prod(dim(data2$data)[time_dim] * dim(data2$data)['sdate'])) { dim(data2$Dates$start) <- c(dim(data2$data)[time_dim], dim(data2$data)['sdate']) + } else { + warning("Dimensions in 'data' element 'data$Dates$start' are missed and ", + "all data would be used.") } - } else { - warning("Dimensions in 'data' element 'data$Dates$start' are missed and", - "all data would be used.") } } data1$data <- MergeRefToExp(data1 = data1$data, dates1 = data1$Dates[[1]], - start1 = start1, end1 = end1, - data2 = data2$data, dates2 = data2$Dates[[1]], - start2, end2, time_dim = time_dim, - sdate_dim = sdate_dim, ncores = ncores) + start1 = start1, end1 = end1, + data2 = data2$data, dates2 = data2$Dates[[1]], + start2, end2, time_dim = time_dim, + sdate_dim = sdate_dim, ncores = ncores) dates1 <- SelectPeriodOnDates(data1$Dates[[1]], start = start1, - end = end1, - time_dim = time_dim) + end = end1, + time_dim = time_dim) dates2 <- SelectPeriodOnDates(data2$Dates[[1]], - start = start2, - end = end2, time_dim = time_dim) + start = start2, + end = end2, time_dim = time_dim) # TO DO CONCATENATE DATES res <- Apply(list(dates1, dates2), target_dims = time_dim, - c, output_dims = time_dim, ncores = ncores)$output1 - if (class(data1$Dates[[1]]) == 'Date') { + c, output_dims = time_dim, ncores = ncores)$output1 + if (inherits(data1$Dates[[1]], 'Date')) { data1$Dates <- as.Date(res, origin = '1970-01-01') } else { data1$Dates <- as.POSIXct(res*3600*24, origin = '1970-01-01', tz = 'UTC') @@ -96,26 +123,42 @@ CST_MergeRefToExp <- function(data1, data2, start1, end1, start2, end2, #'Merge a Reference To Experiments #' -#'Some indicators are defined for specific temporal periods (e.g.: summer from June 21st to September 21st). If the initialization forecast date is later than the one required for the indicator (e.g.: July 1st), the user may want to merge past observations, or other reference, to the forecast (or hindcast) to compute the indicator. The function \code{MergeObs2Exp} takes care of this steps. +#'Some indicators are defined for specific temporal periods (e.g.: summer from +#'June 21st to September 21st). If the initialization forecast date is later +#'than the one required for the indicator (e.g.: July 1st), the user may want to +#'merge past observations, or other reference, to the forecast (or hindcast) to +#'compute the indicator. The function \code{MergeObs2Exp} takes care of this +#'steps. #' -#'@param data1 a multidimensional array with named dimensions. -#'@param dates1 a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data1'. -#'@param data2 a multidimensional array with named dimensions. -#'@param dates2 a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data2'. -#'@param start1 a list to defined the initial date of the period to select from data1 by providing a list of two elements: the initial date of the period and the initial month of the period. -#'@param end1 a list to defined the final date of the period to select from data1 by providing a list of two elements: the final day of the period and the final month of the period. -#'@param start2 a list to defined the initial date of the period to select from data2 by providing a list of two elements: the initial date of the period and the initial month of the period. -#'@param end2 a list to defined the final date of the period to select from data2 by providing a list of two elements: the final day of the period and the final month of the period. -#'@param time_dim a character string indicating the name of the temporal dimension. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. This dimension is required to subset the data in a requested period. -#'@param sdate_dim a character string indicating the name of the dimension in which the initialization dates are stored. -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data1 A multidimensional array with named dimensions. +#'@param dates1 a vector of dates or a multidimensional array of dates with +#' named dimensions matching the dimensions on parameter 'data1'. +#'@param data2 A multidimensional array with named dimensions. +#'@param dates2 A vector of dates or a multidimensional array of dates with +#' named dimensions matching the dimensions on parameter 'data2'. +#'@param start1 A list to define the initial date of the period to select from +#' data1 by providing a list of two elements: the initial date of the period +#' and the initial month of the period. +#'@param end1 A list to define the final date of the period to select from +#' data1 by providing a list of two elements: the final day of the period and +#' the final month of the period. +#'@param start2 A list to define the initial date of the period to select from +#' data2 by providing a list of two elements: the initial date of the period +#' and the initial month of the period. +#'@param end2 A list to define the final date of the period to select from +#' data2 by providing a list of two elements: the final day of the period and +#' the final month of the period. +#'@param time_dim A character string indicating the name of the temporal +#' dimension. By default, it is set to 'ftime'. More than one dimension name +#' matching the dimensions provided in the object \code{data$data} can be +#' specified. This dimension is required to subset the data in a requested period. +#'@param sdate_dim A character string indicating the name of the dimension in +#' which the initialization dates are stored. +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' #'@return A multidimensional array with named dimensions. #' -#'@import multiApply -#'@importFrom ClimProjDiags Subset -#'@importFrom s2dv InsertDim -#' #'@examples #'data_dates <- c(seq(as.Date("01-07-1993", "%d-%m-%Y", tz = 'UTC'), #' as.Date("01-12-1993","%d-%m-%Y", tz = 'UTC'), "day"), @@ -130,6 +173,10 @@ CST_MergeRefToExp <- function(data1, data2, start1, end1, start2, end2, #'new_data <- MergeRefToExp(data1 = ref, dates1 = ref_dates, start1 = list(21, 6), #' end1 = list(30, 6), data2 = data, dates2 = data_dates, #' start2 = list(1, 7), end = list(21, 9)) +#' +#'@import multiApply +#'@importFrom ClimProjDiags Subset +#'@importFrom s2dv InsertDim #'@export MergeRefToExp <- function(data1, dates1, start1, end1, data2, dates2, start2, end2, time_dim = 'time', sdate_dim = 'sdate', @@ -143,16 +190,19 @@ MergeRefToExp <- function(data1, dates1, start1, end1, data2, dates2, start2, en names(dim(data2)) <- time_dim } if (is.null(dim(dates1))) { + warning("Dimensions in 'dates1' element are missed and ", + "all data would be used.") dim(dates1) <- length(dates1) names(dim(dates1)) <- time_dim } if (is.null(dim(dates2))) { + warning("Dimensions in 'dates2' element are missed and ", + "all data would be used.") dim(dates2) <- length(dates2) names(dim(dates2)) <- time_dim } data1 <- SelectPeriodOnData(data1, dates = dates1, start = start1, - end = end1, - time_dim = time_dim, ncores = ncores) + end = end1, time_dim = time_dim, ncores = ncores) # Check if data2 has dimension sdate_dim and it should be added to data1: if ((sdate_dim %in% names(dim(data2))) && dim(data2)[sdate_dim] > 1 && !sdate_dim %in% names(dim(data1))) { @@ -171,7 +221,7 @@ MergeRefToExp <- function(data1, dates1, start1, end1, data2, dates2, start2, en if (length(dif_dims) > 0) { for (i in dif_dims) { data1 <- s2dv::InsertDim(data1, posdim = i, lendim = dim(data2)[i], - name = names(dim(data2))[i], ncores = ncores) + name = names(dim(data2))[i]) } } } @@ -181,14 +231,14 @@ MergeRefToExp <- function(data1, dates1, start1, end1, data2, dates2, start2, en if (length(dif_dims) > 0) { for (i in dif_dims) { data2 <- s2dv::InsertDim(data2, posdim = i, lendim = dim(data1)[i], - name = names(dim(data1))[i], ncores = ncores) + name = names(dim(data1))[i]) } } } data2 <- SelectPeriodOnData(data2, dates = dates2, start = start2, - end = end2, time_dim = time_dim, ncores = ncores) + end = end2, time_dim = time_dim, ncores = ncores) data1 <- Apply(list(data1, data2), target_dims = time_dim, fun = 'c', - output_dims = time_dim, ncores = ncores)$output1 + output_dims = time_dim, ncores = ncores)$output1 return(data1) } diff --git a/R/PeriodAccumulation.R b/R/PeriodAccumulation.R index f9cdb1873bb10a2eee90e7433ac69ed1fa4a57aa..0b3fde5a909e212859875e07a70fb79a424410bf 100644 --- a/R/PeriodAccumulation.R +++ b/R/PeriodAccumulation.R @@ -1,39 +1,60 @@ #'Period Accumulation on 's2dv_cube' objects #' -#'Period Accumulation computes the sum (accumulation) of a given variable in a period. -#'Providing precipitation data, two agriculture indices can be obtained by using this function: +#'Period Accumulation computes the sum (accumulation) of a given variable in a +#'period. Providing precipitation data, two agriculture indices can be obtained +#'by using this function: #'\itemize{ -#' \item\code{SprR}{Spring Total Precipitation: The total precipitation from April 21th to June 21st} -#' \item\code{HarR}{Harvest Total Precipitation: The total precipitation from August 21st to October 21st}} +#' \item\code{SprR}{Spring Total Precipitation: The total precipitation from +#' April 21th to June 21st} +#' \item\code{HarR}{Harvest Total Precipitation: The total precipitation from +#' August 21st to October 21st} +#'} #' -#'@param data an 's2dv_cube' object as provided function \code{CST_Load} in package CSTools. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param na.rm a logical value indicating whether to ignore NA values (TRUE) or not (FALSE). -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data An 's2dv_cube' object as provided function \code{CST_Load} in +#' package CSTools. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the dimension to +#' compute the indicator. By default, it is set to 'ftime'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param na.rm A logical value indicating whether to ignore NA values (TRUE) or +#' not (FALSE). +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A 's2dv_cube' object containing the indicator in the element \code{data}. -#' -#'@import multiApply +#'@return A 's2dv_cube' object containing the indicator in the element +#'\code{data}. #' #'@examples -#'exp <- CSTools::lonlat_prec +#'exp <- NULL +#'exp$data <- array(rnorm(216)*200, dim = c(dataset = 1, member = 2, sdate = 3, +#' ftime = 9, lat = 2, lon = 2)) +#'class(exp) <- 's2dv_cube' #'TP <- CST_PeriodAccumulation(exp) #'exp$data <- array(rnorm(5 * 3 * 214 * 2), #' c(memb = 5, sdate = 3, ftime = 214, lon = 2)) #'exp$Dates[[1]] <- c(seq(as.Date("01-05-2000", format = "%d-%m-%Y"), -#' as.Date("30-11-2000", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), -#' as.Date("30-11-2001", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), -#' as.Date("30-11-2002", format = "%d-%m-%Y"), by = 'day')) +#' as.Date("30-11-2000", format = "%d-%m-%Y"), by = 'day'), +#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), +#' as.Date("30-11-2001", format = "%d-%m-%Y"), by = 'day'), +#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), +#' as.Date("30-11-2002", format = "%d-%m-%Y"), by = 'day')) #'SprR <- CST_PeriodAccumulation(exp, start = list(21, 4), end = list(21, 6)) #'dim(SprR$data) #'head(SprR$Dates) #'HarR <- CST_PeriodAccumulation(exp, start = list(21, 8), end = list(21, 10)) #'dim(HarR$data) #'head(HarR$Dates) +#' +#'@import multiApply #'@export CST_PeriodAccumulation <- function(data, start = NULL, end = NULL, time_dim = 'ftime', na.rm = FALSE, @@ -50,10 +71,10 @@ CST_PeriodAccumulation <- function(data, start = NULL, end = NULL, prod(dim(data$data)[time_dim] * dim(data$data)['sdate'])) { dim(data$Dates$start) <- c(dim(data$data)[time_dim], dim(data$data)['sdate']) + } else { + warning("Dimensions in 'data' element 'Dates$start' are missed and ", + "all data would be used.") } - } else { - warning("Dimensions in 'data' element 'Dates$start' are missed and", - "all data would be used.") } } } @@ -62,45 +83,65 @@ CST_PeriodAccumulation <- function(data, start = NULL, end = NULL, data$data <- total if (!is.null(start) && !is.null(end)) { data$Dates <- SelectPeriodOnDates(dates = data$Dates[[1]], - start = start, end = end, - time_dim = time_dim, ncores = ncores) + start = start, end = end, + time_dim = time_dim, ncores = ncores) } return(data) } #'Period Accumulation on multidimensional array objects #' -#'Period Accumulation computes the sum (accumulation) of a given variable in a period. -#'Providing precipitation data, two agriculture indices can be obtained by using this function: +#'Period Accumulation computes the sum (accumulation) of a given variable in a +#'period. Providing precipitation data, two agriculture indices can be obtained +#'by using this function: #'\itemize{ -#' \item\code{SprR}{Spring Total Precipitation: The total precipitation from April 21th to June 21st} -#' \item\code{HarR}{Harvest Total Precipitation: The total precipitation from August 21st to October 21st}} +#' \item\code{SprR}{Spring Total Precipitation: The total precipitation from +#' April 21th to June 21st} +#' \item\code{HarR}{Harvest Total Precipitation: The total precipitation from +#' August 21st to October 21st} +#'} #' -#'@param data a multidimensional array with named dimensions. -#'@param dates a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the function to compute the indicator. By default, it is set to 'time'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param na.rm a logical value indicating whether to ignore NA values (TRUE) or not (FALSE). -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data A multidimensional array with named dimensions. +#'@param dates A vector of dates or a multidimensional array of dates with named +#' dimensions matching the dimensions on parameter 'data'. By default it is +#' NULL, to select a period this parameter must be provided. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the dimension to +#' compute the indicator. By default, it is set to 'time'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param na.rm A logical value indicating whether to ignore NA values (TRUE) or +#' not (FALSE). +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A multidimensional array with named dimensions. -#' -#'@import multiApply +#'@return A multidimensional array with named dimensions containing the +#'indicator in the element \code{data}. #' #'@examples -#'exp <- CSTools::lonlat_prec$data +#'exp <- array(rnorm(216)*200, dim = c(dataset = 1, member = 2, sdate = 3, +#' ftime = 9, lat = 2, lon = 2)) #'TP <- PeriodAccumulation(exp, time_dim = 'ftime') #'data <- array(rnorm(5 * 3 * 214 * 2), #' c(memb = 5, sdate = 3, time = 214, lon = 2)) #'# ftime tested #'Dates <- c(seq(as.Date("01-05-2000", format = "%d-%m-%Y"), #' as.Date("30-11-2000", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), +#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), #' as.Date("30-11-2001", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), +#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), #' as.Date("30-11-2002", format = "%d-%m-%Y"), by = 'day')) #'SprR <- PeriodAccumulation(data, dates = Dates, start = list(21, 4), end = list(21, 6)) #'HarR <- PeriodAccumulation(data, dates = Dates, start = list(21, 8), end = list(21, 10)) +#' +#'@import multiApply #'@export PeriodAccumulation <- function(data, dates = NULL, start = NULL, end = NULL, time_dim = 'time', na.rm = FALSE, diff --git a/R/PeriodMean.R b/R/PeriodMean.R index fa3af031194e7a13f50acccdbcd7eee4eae1ca8c..97f99c3c309dad36392a23d214148c188a3d1290 100644 --- a/R/PeriodMean.R +++ b/R/PeriodMean.R @@ -1,27 +1,49 @@ #'Period Mean on 's2dv_cube' objects #' #'Period Mean computes the average (mean) of a given variable in a period. -#'Providing temperature data, two agriculture indices can be obtain by using this function: +#'Providing temperature data, two agriculture indices can be obtained by using +#'this function: #'\itemize{ -#' \item\code{GST}{Growing Season average Temperature: The average temperature from April 1st to Octobe 31st} -#' \item\code{SprTX}{Spring Average Maximum Temperature: The average daily maximum temperature from April 1st to May 31st}} +#' \item\code{GST}{Growing Season average Temperature: The average temperature +#' from April 1st to Octobe 31st} +#' \item\code{SprTX}{Spring Average Maximum Temperature: The average daily +#' maximum temperature from April 1st to May 31st} +#'} #' -#'@param data an 's2dv_cube' object as provided function \code{CST_Load} in package CSTools. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param na.rm a logical value indicating whether to ignore NA values (TRUE) or not (FALSE). -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data An 's2dv_cube' object as provided function \code{CST_Load} in +#' package CSTools. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the dimension to +#' compute the indicator. By default, it is set to 'ftime'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param na.rm A logical value indicating whether to ignore NA values (TRUE) or +#' not (FALSE). +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A 's2dv_cube' object containing the indicator in the element \code{data}. -#' -#'@import multiApply +#'@return An 's2dv_cube' object containing the indicator in the element +#' \code{data}. #' #'@examples -#'exp <- CSTools::lonlat_data$exp -#'exp$data <- CSTools::lonlat_data$exp$data[1, , 3, , 1, 1] +#'exp <- NULL +#'exp$data <- array(rnorm(45), dim = c(member = 7, ftime = 8)) +#'class(exp) <- 's2dv_cube' +#'exp$Dates$start <- c(seq(as.Date("01-07-1993", "%d-%m-%Y", tz = 'UTC'), +#' as.Date("01-08-1993","%d-%m-%Y", tz = 'UTC'), "day"), +#' seq(as.Date("01-07-1994", "%d-%m-%Y", tz = 'UTC'), +#' as.Date("01-08-1994","%d-%m-%Y", tz = 'UTC'), "day")) #'SA <- CST_PeriodMean(exp) #' +#'@import multiApply #'@export CST_PeriodMean <- function(data, start = NULL, end = NULL, time_dim = 'ftime', na.rm = FALSE, @@ -39,9 +61,9 @@ CST_PeriodMean <- function(data, start = NULL, end = NULL, prod(dim(data$data)[time_dim] * dim(data$data)['sdate'])) { dim(data$Dates$start) <- c(dim(data$data)[time_dim], dim(data$data)['sdate']) + } else { + warning("Dimensions in 'data' element 'Dates$start' are missed/unmatched. All data would be used.") } - } else { - warning("Dimensions in 'data' element 'Dates$start' are missed/unmatched. All data would be used.") } } } @@ -59,26 +81,45 @@ CST_PeriodMean <- function(data, start = NULL, end = NULL, #'Period Mean on multidimensional array objects #' #'Period Mean computes the average (mean) of a given variable in a period. -#'Providing temperature data, two agriculture indices can be obtain by using this function: +#'Providing temperature data, two agriculture indices can be obtained by using +#'this function: #'\itemize{ -#' \item\code{GST}{Growing Season average Temperature: The average temperature from April 1st to Octobe 31st} -#' \item\code{SprTX}{Spring Average Maximum Temperature: The average daily maximum temperature from April 1st to May 31st}} +#' \item\code{GST}{Growing Season average Temperature: The average +#' temperature from April 1st to Octobe 31st} +#' \item\code{SprTX}{Spring Average Maximum Temperature: The average daily +#' maximum temperature from April 1st to May 31st} +#'} #' -#'@param data a multidimensional array with named dimensions. -#'@param dates a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param na.rm a logical value indicating whether to ignore NA values (TRUE) or not (FALSE). -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data A multidimensional array with named dimensions. +#'@param dates A vector of dates or a multidimensional array of dates with named +#' dimensions matching the dimensions on parameter 'data'. By default it is +#' NULL, to select a period this parameter must be provided. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the dimension to +#' compute the indicator. By default, it is set to 'ftime'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param na.rm A logical value indicating whether to ignore NA values (TRUE) or +#' not (FALSE). +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A multidimensional array with named dimensions. -#' -#'@import multiApply +#'@return A multidimensional array with named dimensions containing the +#'indicator in the element \code{data}. #' #'@examples -#'exp <- CSTools::lonlat_prec$data +#'exp <- array(rnorm(56), dim = c(member = 7, ftime = 8)) #'SA <- PeriodMean(exp, time_dim = 'ftime') +#' +#'@import multiApply #'@export PeriodMean <- function(data, dates = NULL, start = NULL, end = NULL, time_dim = 'time', na.rm = FALSE, ncores = NULL) { diff --git a/R/QThreshold.R b/R/QThreshold.R index 067c495bb9ffbaa32eeff9a5a9137739f37550c2..8eb950a76a255138e5c930c3a2d4f0414496c605 100644 --- a/R/QThreshold.R +++ b/R/QThreshold.R @@ -1,43 +1,74 @@ #'Transform an absolute threshold into probabilities #' -#'From a user perspective, an absolute threshold can be very useful for a specific needs (e.g.: grape variety). -#' However, this absolute threshold could be transform to a relative threshold in order to get its frequency in a given dataset. -#'Therefore, the function \code{QThreshold} returns the probability of an absolute threshold. -#'This is done by computing the Cumulative Distribution Function of a sample and leaving-one-ot. -#' The sample used will depend on the dimensions of the data provided and the dimension names provided in sdate_dim and memb_dim parameters: +#'From the user's perspective, an absolute threshold can be very useful for a +#'specific needs (e.g.: grape variety). However, this absolute threshold could +#'be transformed to a relative threshold in order to get its frequency in a given +#'dataset. Therefore, the function \code{QThreshold} returns the probability of +#'an absolute threshold. This is done by computing the Cumulative Distribution +#'Function of a sample and leaving one out. The sample used will depend on the +#'dimensions of the data provided and the dimension names provided in sdate_dim +#'and memb_dim parameters: +#' #'\itemize{ -#' \item{Wheter a forecast (hindcast) has dimensions member and start date, and both must be used in the sample, their names should be passed in sdate_dim and memb_dim.} -#' \item{Wheter a forecast (hindcast) has dimensions member and start date, and only start date must be used in the sample (the calculation is done in each separate member), memb_dim can be set to NULL.} -#' \item{Wheter a reference (observations) has start date dimension, the sample used is the start date dimension.} -#' \item{Wheter a reference (observations) doesn't have start date dimension, the sample used must be especified in sdate_dim parameter.}} +#' \item{If a forecast (hindcast) has dimensions member and start date, and +#' both must be used in the sample, their names should be passed in +#' sdate_dim and memb_dim.} +#' \item{If a forecast (hindcast) has dimensions member and start date, and +#' only start date must be used in the sample (the calculation is done in +#' each separate member), memb_dim can be set to NULL.} +#' \item{If a reference (observations) has start date dimension, the sample +#' used is the start date dimension.} +#' \item{If a reference (observations) doesn't have start date dimension, +#' the sample used must be especified in sdate_dim parameter.} +#'} #' -#'@param data an 's2dv_cube' object as provided function \code{CST_Load} in package CSTools. -#'@param threshold an 's2dv_cube' object as output of a 'CST_' function in the same units as parameter 'data' and with the common dimensions of the element 'data' of the same length. A single scalar is also possible. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the temporal dimension. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. This dimension is required to subset the data in a requested period. -#'@param memb_dim a character string indicating the name of the dimension in which the ensemble members are stored. -#'@param sdate_dim a character string indicating the name of the dimension in which the initialization dates are stored. -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data An 's2dv_cube' object as provided function \code{CST_Load} in +#' package CSTools. +#'@param threshold An 's2dv_cube' object as output of a 'CST_' function in the +#' same units as parameter 'data' and with the common dimensions of the element +#' 'data' of the same length. A single scalar is also possible. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the temporal +#' dimension. By default, it is set to 'ftime'. More than one dimension name +#' matching the dimensions provided in the object \code{data$data} can be +#' specified. This dimension is required to subset the data in a requested +#' period. +#'@param memb_dim A character string indicating the name of the dimension in +#' which the ensemble members are stored. +#'@param sdate_dim A character string indicating the name of the dimension in +#' which the initialization dates are stored. +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A 's2dv_cube' object containing the probabilites in the element \code{data}. -#' -#'@import multiApply -#'@importFrom ClimProjDiags Subset +#'@return An 's2dv_cube' object containing the probability of an absolute +#'threshold in the element \code{data}. #' #'@examples #'threshold <- 26 -#'exp <- CSTools::lonlat_prec +#'exp <- NULL +#'exp$data <- array(abs(rnorm(112)*26), dim = c(member = 7, sdate = 8, ftime = 2)) +#'class(exp) <- 's2dv_cube' #'exp_probs <- CST_QThreshold(exp, threshold) #'exp$data <- array(rnorm(5 * 3 * 214 * 2), #' c(member = 5, sdate = 3, ftime = 214, lon = 2)) #'exp$Dates[[1]] <- c(seq(as.Date("01-05-2000", format = "%d-%m-%Y"), -#' as.Date("30-11-2000", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), -#' as.Date("30-11-2001", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), -#' as.Date("30-11-2002", format = "%d-%m-%Y"), by = 'day')) -#'exp_probs <- CST_QThreshold(exp, threshold, start = list(21, 4), end = list(21, 6)) +#' as.Date("30-11-2000", format = "%d-%m-%Y"), by = 'day'), +#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), +#' as.Date("30-11-2001", format = "%d-%m-%Y"), by = 'day'), +#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), +#' as.Date("30-11-2002", format = "%d-%m-%Y"), by = 'day')) +#'exp_probs <- CST_QThreshold(exp, threshold) +#' +#'@import multiApply +#'@importFrom ClimProjDiags Subset #'@export CST_QThreshold <- function(data, threshold, start = NULL, end = NULL, time_dim = 'ftime', memb_dim = 'member', sdate_dim = 'sdate', @@ -51,13 +82,13 @@ CST_QThreshold <- function(data, threshold, start = NULL, end = NULL, if (is.null(dim(data$Dates$start))) { if (length(data$Dates$start) != dim(data$data)[time_dim]) { if (length(data$Dates$start) == - prod(dim(data$data)[time_dim] * dim(data$data)['sdate'])) { + prod(dim(data$data)[time_dim] * dim(data$data)[sdate_dim])) { dim(data$Dates$start) <- c(dim(data$data)[time_dim], - dim(data$data)['sdate']) + dim(data$data)[sdate_dim]) + } else { + warning("Dimensions in 'data' element 'Dates$start' are missed and ", + "all data would be used.") } - } else { - warning("Dimensions in 'data' element 'Dates$start' are missed and", - "all data would be used.") } } } @@ -77,36 +108,66 @@ CST_QThreshold <- function(data, threshold, start = NULL, end = NULL, } #'Transform an absolute threshold into probabilities #' -#'From a user perspective, an absolute threshold can be very useful for a specific needs (e.g.: grape variety). -#' However, this absolute threshold could be transform to a relative threshold in order to get its frequency in a given dataset. -#'Therefore, the function \code{QThreshold} returns the probability of an absolute threshold. -#'This is done by computing the Cumulative Distribution Function of a sample and leaving-one-ot. -#' The sample used will depend on the dimensions of the data provided and the dimension names provided in sdate_dim and memb_dim parameters: +#'From the user's perspective, an absolute threshold can be very useful for a +#'specific needs (e.g.: grape variety). However, this absolute threshold could +#'be transformed to a relative threshold in order to get its frequency in a given +#'dataset. Therefore, the function \code{QThreshold} returns the probability of +#'an absolute threshold. This is done by computing the Cumulative Distribution +#'Function of a sample and leaving-one-ot. The sample used will depend on the +#'dimensions of the data provided and the dimension names provided in sdate_dim +#'and memb_dim parameters: #'\itemize{ -#' \item{Wheter a forecast (hindcast) has dimensions member and start date, and both must be used in the sample, their names should be passed in sdate_dim and memb_dim.} -#' \item{Wheter a forecast (hindcast) has dimensions member and start date, and only start date must be used in the sample (the calculation is done in each separate member), memb_dim can be set to NULL.} -#' \item{Wheter a reference (observations) has start date dimension, the sample used is the start date dimension.} -#' \item{Wheter a reference (observations) doesn't have start date dimension, the sample used must be especified in sdate_dim parameter.}} +#' \item{If a forecast (hindcast) has dimensions member and start date, and +#' both must be used in the sample, their names should be passed in +#' sdate_dim and memb_dim.} +#' \item{If a forecast (hindcast) has dimensions member and start date, and +#' only start date must be used in the sample (the calculation is done in +#' each separate member), memb_dim can be set to NULL.} +#' \item{If a reference (observations) has start date dimension, the sample +#' used is the start date dimension.} +#' \item{If a reference (observations) doesn't have start date dimension, +#' the sample used must be especified in sdate_dim parameter.} +#'} #' -#'@param data a multidimensional array with named dimensions. -#'@param threshold a multidimensional array with named dimensions in the same units as parameter 'data' and with the common dimensions of the element 'data' of the same length. -#'@param dates a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the temporal dimension. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. This dimension is required to subset the data in a requested period. -#'@param memb_dim a character string indicating the name of the dimension in which the ensemble members are stored. -#'@param sdate_dim a character string indicating the name of the dimension in which the initialization dates are stored. -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data A multidimensional array with named dimensions. +#'@param threshold A multidimensional array with named dimensions in the same +#' units as parameter 'data' and with the common dimensions of the element +#' 'data' of the same length. +#'@param dates A vector of dates or a multidimensional array of dates with named +#' dimensions matching the dimensions on parameter 'data'. By default it is +#' NULL, to select a period this parameter must be provided. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the temporal +#' dimension. By default, it is set to 'ftime'. More than one dimension name +#' matching the dimensions provided in the object \code{data$data} can be +#' specified. This dimension is required to subset the data in a requested +#' period. +#'@param memb_dim A character string indicating the name of the dimension in +#' which the ensemble members are stored. +#'@param sdate_dim A character string indicating the name of the dimension in +#' which the initialization dates are stored. +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A multidimensional array with named dimensions. +#'@return A multidimensional array with named dimensions containing the +#'probability of an absolute threshold in the element \code{data}. #' -#'@import multiApply -#'@importFrom ClimProjDiags Subset #'@examples #'threshold = 25 #'data <- array(rnorm(5 * 3 * 20 * 2, mean = 26), #' c(member = 5, sdate = 3, time = 20, lon = 2)) #'thres_q <- QThreshold(data, threshold) +#' +#'@import multiApply +#'@importFrom ClimProjDiags Subset #'@export QThreshold <- function(data, threshold, dates = NULL, start = NULL, end = NULL, time_dim = 'time', memb_dim = 'member', sdate_dim = 'sdate', @@ -154,10 +215,10 @@ QThreshold <- function(data, threshold, dates = NULL, start = NULL, end = NULL, if (!is.null(dim(dates)) && sdate_dim %in% dim(dates)) { dates_thres <- Subset(dates, along = sdate_dim, indices = 1) threshold <- SelectPeriodOnData(threshold, dates_thres, start, end, - time_dim = time_dim, ncores = ncores) + time_dim = time_dim, ncores = ncores) } else { - threshold <- SelectPeriodOnData(threshold, dates, start, end, - time_dim = time_dim, ncores = ncores) + threshold <- SelectPeriodOnData(threshold, dates, start, end, + time_dim = time_dim, ncores = ncores) } } } @@ -204,7 +265,7 @@ QThreshold <- function(data, threshold, dates = NULL, start = NULL, end = NULL, dims <- dim(data) # no 'member' involving qres <- unlist(lapply(1:dims, function(x) { - ecdf(data[-x])(threshold)})) + ecdf(data[-x])(threshold)})) dim(qres) <- c(dims) return(qres) } @@ -212,8 +273,8 @@ QThreshold <- function(data, threshold, dates = NULL, start = NULL, end = NULL, qres <- unlist( lapply(1:(dim(data)[1]), function(x) { # dim 1: member lapply(1:(dim(data)[2]), function(y) { # dim 2: sdate - ecdf(as.vector(data[,-y]))(threshold) - }) + ecdf(as.vector(data[,-y]))(threshold) + }) })) dim(qres) <- c(dim(data)[2], dim(data)[1]) return(qres) diff --git a/R/SelectPeriodOnData.R b/R/SelectPeriodOnData.R index a6f9c295a37dd5c2e4051ec5a9d42b14dee1231f..3c162dd746340feb909a9a19ea615ee9081a94a1 100644 --- a/R/SelectPeriodOnData.R +++ b/R/SelectPeriodOnData.R @@ -2,27 +2,38 @@ #' #' Auxiliary function to subset data for a specific period. #' -#'@param data an 's2dv_cube' object as provided function \code{CST_Load} in package CSTools. -#'@param start a parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. -#'@param end a parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. -#'@param time_dim a character string indicating the name of the dimension to compute select the dates. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data An 's2dv_cube' object as provided function \code{CST_Load} in +#' package CSTools. +#'@param start A parameter to defined the initial date of the period to select +#' from the data by providing a list of two elements: the initial date of the +#' period and the initial month of the period. +#'@param end A parameter to defined the final date of the period to select from +#' the data by providing a list of two elements: the final day of the period +#' and the final month of the period. +#'@param time_dim A character string indicating the name of the dimension to +#' compute select the dates. By default, it is set to 'ftime'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A 's2dv_cube' object containing the subset of the object \code{data$data} during the period requested from \code{start} to \code{end}. -#' -#'@import multiApply +#'@return A 's2dv_cube' object containing the subset of the object +#'\code{data$data} during the period requested from \code{start} to \code{end}. #' #'@examples -#'exp <- CSTools::lonlat_prec +#'exp <- NULL #'exp$data <- array(rnorm(5 * 3 * 214 * 2), -#' c(memb = 5, sdate = 3, ftime = 214, lon = 2)) -#'exp$Dates[[1]] <- c(seq(as.Date("01-05-2000", format = "%d-%m-%Y"), -#' as.Date("30-11-2000", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), -#' as.Date("30-11-2001", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), -#' as.Date("30-11-2002", format = "%d-%m-%Y"), by = 'day')) +#' c(memb = 5, sdate = 3, ftime = 214, lon = 2)) +#'exp$Dates$start <- c(seq(as.Date("01-05-2000", format = "%d-%m-%Y"), +#' as.Date("30-11-2000", format = "%d-%m-%Y"), by = 'day'), +#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), +#' as.Date("30-11-2001", format = "%d-%m-%Y"), by = 'day'), +#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), +#' as.Date("30-11-2002", format = "%d-%m-%Y"), by = 'day')) +#'class(exp) <- 's2dv_cube' #'Period <- CST_SelectPeriodOnData(exp, start = list(21, 6), end = list(21, 9)) +#' +#'@import multiApply #'@export CST_SelectPeriodOnData <- function(data, start, end, time_dim = 'ftime', ncores = NULL) { if (!inherits(data, 's2dv_cube')) { @@ -37,10 +48,10 @@ CST_SelectPeriodOnData <- function(data, start, end, time_dim = 'ftime', ncores prod(dim(data$data)[time_dim] * dim(data$data)['sdate'])) { dim(data$Dates$start) <- c(dim(data$data)[time_dim], dim(data$data)['sdate']) + } else { + warning("Dimensions in 'data' element 'Dates$start' are missed and ", + "all data would be used.") } - } else { - warning("Dimensions in 'data' element 'Dates$start' are missed and", - "all data would be used.") } } } @@ -50,8 +61,8 @@ CST_SelectPeriodOnData <- function(data, start, end, time_dim = 'ftime', ncores data$data <- res if (!is.null(start) && !is.null(end)) { data$Dates <- SelectPeriodOnDates(dates = data$Dates[[1]], - start = start, end = end, - time_dim = time_dim, ncores = ncores) + start = start, end = end, + time_dim = time_dim, ncores = ncores) } return(data) } @@ -61,29 +72,39 @@ CST_SelectPeriodOnData <- function(data, start, end, time_dim = 'ftime', ncores #' #' Auxiliary function to subset data for a specific period. #' -#'@param data a multidimensional array with named dimensions. -#'@param dates a vector of dates or a multidimensional array of dates with named dimensions. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. -#'@param time_dim a character string indicating the name of the dimension to compute select the dates. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data A multidimensional array with named dimensions. +#'@param dates A vector of dates or a multidimensional array of dates with named +#' dimensions. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. +#'@param time_dim A character string indicating the name of the dimension to +#' compute select the dates. By default, it is set to 'ftime'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A multidimensional array with named dimensions. -#' -#'@import multiApply +#'@return A multidimensional array with named dimensions containing the subset +#'of the object \code{data} during the period requested from \code{start} to +#'\code{end}. #' #'@examples #'data <- array(rnorm(5 * 3 * 214 * 2), -#' c(memb = 5, sdate = 3, ftime = 214, lon = 2)) +#' c(memb = 5, sdate = 3, ftime = 214, lon = 2)) #'Dates <- c(seq(as.Date("01-05-2000", format = "%d-%m-%Y"), #' as.Date("30-11-2000", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), +#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), #' as.Date("30-11-2001", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), +#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), #' as.Date("30-11-2002", format = "%d-%m-%Y"), by = 'day')) #'dim(Dates) <- c(ftime = 214, sdate = 3) #'Period <- SelectPeriodOnData(data, Dates, start = list(21, 6), end = list(21, 9)) #' +#'@import multiApply #'@export SelectPeriodOnData <- function(data, dates, start, end, time_dim = 'ftime', ncores = NULL) { @@ -121,6 +142,11 @@ SelectPeriodOnData <- function(data, dates, start, end, res <- Apply(list(data, res), target_dims = time_dim, fun = function(x, y) { res <- x[y] + if (is.null(dim(res))) { + dim(res) <- 1 + names(dim(res)) <- time_dim + } + return(res) }, output_dims = time_dim, ncores = ncores)$output1 } return(res) diff --git a/R/SelectPeriodOnDates.R b/R/SelectPeriodOnDates.R index c8444c03fa28d9712e0cde44f45ad0aa11b5a2a8..a9c8d9c834a9b8a4963e71d78455b3121737c926 100644 --- a/R/SelectPeriodOnDates.R +++ b/R/SelectPeriodOnDates.R @@ -2,13 +2,23 @@ #' #' Auxiliary function to subset dates for a specific period. #' -#'@param dates a vector of dates or a multidimensional array of dates with named dimensions. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. -#'@param time_dim a character string indicating the name of the dimension to compute select the dates. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param dates A vector of dates or a multidimensional array of dates with named +#' dimensions. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. +#'@param time_dim A character string indicating the name of the dimension to +#' compute select the dates. By default, it is set to 'ftime'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A multidimensional array with named dimensions. +#'@return A multidimensional array with named dimensions containing the subset of +#'the vector dates during the period requested from \code{start} to \code{end}. #' #'@import multiApply #'@importFrom s2dv Reorder @@ -16,14 +26,14 @@ #'@examples #'Dates <- c(seq(as.Date("01-05-2000", format = "%d-%m-%Y"), #' as.Date("30-11-2000", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), +#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), #' as.Date("30-11-2001", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), +#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), #' as.Date("30-11-2002", format = "%d-%m-%Y"), by = 'day')) #'Period <- SelectPeriodOnDates(Dates, start = list(21, 6), end = list(21, 9)) #'@export SelectPeriodOnDates <- function(dates, start, end, - time_dim = 'ftime', ncores = NULL) { + time_dim = 'ftime', ncores = NULL) { # TODO: consider NAs if (is.null(dim(dates))) { dim(dates) <- length(dates) diff --git a/R/Threshold.R b/R/Threshold.R index c09ebe004fe6424f41edcf1623f058ca24ebb225..0117952a9ece29ca03caa68b1880c836455016e7 100644 --- a/R/Threshold.R +++ b/R/Threshold.R @@ -1,40 +1,61 @@ #'Absolute value of a relative threshold (percentile) #' -#'Frequently, thresholds are defined by a percentile that may correspond to a different absolute value depending on the variable, gridpoint and also julian day (time). -#' This function calculates the corresponding value of a percentile given a dataset. +#'Frequently, thresholds are defined by a percentile that may correspond to a +#'different absolute value depending on the variable, gridpoint and also julian +#'day (time). This function calculates the corresponding value of a percentile +#'given a dataset. #' -#'@param data an 's2dv_cube' object as provided function \code{CST_Load} in package CSTools. -#'@param threshold a single scalar or vector indicating the relative threshold(s). -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the temporal dimension. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. This dimension is required to subset the data in a requested period. -#'@param memb_dim a character string indicating the name of the dimension in which the ensemble members are stored. When set it to NULL, threshold is computed for individual members. -#'@param sdate_dim a character string indicating the name of the dimension in which the initialization dates are stored. -#'@param na.rm a logical value indicating whether to ignore NA values (TRUE) or not (FALSE). -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data An 's2dv_cube' object as provided function \code{CST_Load} in +#' package CSTools. +#'@param threshold A single scalar or vector indicating the relative +#' threshold(s). +#'@param start An optional parameter to defined the initial date of the period +#' to selectfrom the data by providing a list of two elements: the initial date +#' of the period and the initial month of the period. By default it is set to +#' NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the temporal +#' dimension. By default, it is set to 'ftime'. More than one dimension name +#' matching the dimensions provided in the object \code{data$data} can be +#' specified. This dimension is required to subset the data in a requested +#' period. +#'@param memb_dim A character string indicating the name of the dimension in +#' which the ensemble members are stored. When set it to NULL, threshold is +#' computed for individual members. +#'@param sdate_dim A character string indicating the name of the dimension in +#' which the initialization dates are stored. +#'@param na.rm A logical value indicating whether to ignore NA values (TRUE) or +#' not (FALSE). +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A 's2dv_cube' object containing the probabilites in the element \code{data}. -#' -#'@import multiApply +#'@return An ’s2dv_cube’ object containing the corresponding values of a +#'percentile in the element \code{data}. #' #'@examples #'threshold <- 0.9 -#'exp <- CSTools::lonlat_prec -#'exp_probs <- CST_Threshold(exp, threshold) +#'exp <- NULL #'exp$data <- array(rnorm(5 * 3 * 214 * 2), #' c(member = 5, sdate = 3, ftime = 214, lon = 2)) -#'exp$Dates[[1]] <- c(seq(as.Date("01-05-2000", format = "%d-%m-%Y"), -#' as.Date("30-11-2000", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), -#' as.Date("30-11-2001", format = "%d-%m-%Y"), by = 'day'), -#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), -#' as.Date("30-11-2002", format = "%d-%m-%Y"), by = 'day')) +#'exp$Dates$start <- c(seq(as.Date("01-05-2000", format = "%d-%m-%Y"), +#' as.Date("30-11-2000", format = "%d-%m-%Y"), by = 'day'), +#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), +#' as.Date("30-11-2001", format = "%d-%m-%Y"), by = 'day'), +#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), +#' as.Date("30-11-2002", format = "%d-%m-%Y"), by = 'day')) +#'class(exp) <- 's2dv_cube' #'exp_probs <- CST_Threshold(exp, threshold, start = list(21, 4), end = list(21, 6)) +#' +#'@import multiApply #'@export CST_Threshold <- function(data, threshold, start = NULL, end = NULL, - time_dim = 'ftime', memb_dim = 'member', sdate_dim = 'sdate', - na.rm = FALSE, ncores = NULL) { - if (!inherits(data, 's2dv_cube')) { + time_dim = 'ftime', memb_dim = 'member', sdate_dim = 'sdate', + na.rm = FALSE, ncores = NULL) { + if (!inherits(data, 's2dv_cube')) { stop("Parameter 'data' must be of the class 's2dv_cube', ", "as output by CSTools::CST_Load.") } @@ -43,47 +64,66 @@ CST_Threshold <- function(data, threshold, start = NULL, end = NULL, if (is.null(dim(data$Dates$start))) { if (length(data$Dates$start) != dim(data$data)[time_dim]) { if (length(data$Dates$start) == - prod(dim(data$data)[time_dim] * dim(data$data)['sdate'])) { + prod(dim(data$data)[time_dim] * dim(data$data)[sdate_dim])) { dim(data$Dates$start) <- c(dim(data$data)[time_dim], - dim(data$data)['sdate']) + dim(data$data)[sdate_dim]) + } else { + warning("Dimensions in 'data' element 'Dates$start' are missed and ", + "all data would be used.") } - } else { - warning("Dimensions in 'data' element 'Dates$start' are missed and", - "all data would be used.") } } } thres <- Threshold(data$data, threshold, data$Dates[[1]], start, end, - time_dim = time_dim, memb_dim = memb_dim, - sdate_dim = sdate_dim, na.rm = na.rm, ncores = ncores) + time_dim = time_dim, memb_dim = memb_dim, + sdate_dim = sdate_dim, na.rm = na.rm, ncores = ncores) data$data <- thres if (!is.null(start) && !is.null(end)) { data$Dates <- SelectPeriodOnDates(dates = data$Dates[[1]], - start = start, end = end, - time_dim = time_dim, ncores = ncores) + start = start, end = end, + time_dim = time_dim, ncores = ncores) } return(data) } #'Absolute value of a relative threshold (percentile) #' -#'Frequently, thresholds are defined by a percentile that may correspond to a different absolute value depending on the variable, gridpoint and also julian day (time). -#' This function calculates the corresponding value of a percentile given a dataset. -#' -#'@param data a multidimensional array with named dimensions. -#'@param threshold a single scalar or vector indicating the relative threshold(s). -#'@param dates a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the temporal dimension. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. This dimension is required to subset the data in a requested period. -#'@param memb_dim a character string indicating the name of the dimension in which the ensemble members are stored. When set it to NULL, threshold is computed for individual members. -#'@param sdate_dim a character string indicating the name of the dimension in which the initialization dates are stored. -#'@param na.rm a logical value indicating whether to ignore NA values (TRUE) or not (FALSE). -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'Frequently, thresholds are defined by a percentile that may correspond to a +#'different absolute value depending on the variable, gridpoint and also julian +#'day (time). This function calculates the corresponding value of a percentile +#'given a dataset. #' -#'@return A multidimensional array with named dimensions. +#'@param data A multidimensional array with named dimensions. +#'@param threshold A single scalar or vector indicating the relative +#' threshold(s). +#'@param dates A vector of dates or a multidimensional array of dates with named +#' dimensions matching the dimensions on parameter 'data'. By default it is +#' NULL, to select a period this parameter must be provided. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the temporal +#' dimension. By default, it is set to 'ftime'. More than one dimension name +#' matching the dimensions provided in the object \code{data$data} can be +#' specified. This dimension is required to subset the data in a requested +#' period. +#'@param memb_dim A character string indicating the name of the dimension in +#' which the ensemble members are stored. When set it to NULL, threshold is +#' computed for individual members. +#'@param sdate_dim A character string indicating the name of the dimension in +#' which the initialization dates are stored. +#'@param na.rm A logical value indicating whether to ignore NA values (TRUE) or +#' not (FALSE). +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@import multiApply -#'@importFrom stats quantile +#'@return A multidimensional array with named dimensions containing the +#'corresponding values of a percentile in the element \code{data}. #' #'@examples #'threshold <- 0.9 @@ -92,6 +132,9 @@ CST_Threshold <- function(data, threshold, start = NULL, end = NULL, #'thres_q <- Threshold(data, threshold) #'data <- array(rnorm(1 * 3 * 214 * 2), c(member = 1, sdate = 3, time = 214, lon = 2)) #'res <- Threshold(data, threshold) +#' +#'@import multiApply +#'@importFrom stats quantile #'@export Threshold <- function(data, threshold, dates = NULL, start = NULL, end = NULL, time_dim = 'time', memb_dim = 'member', sdate_dim = 'sdate', @@ -133,11 +176,11 @@ Threshold <- function(data, threshold, dates = NULL, start = NULL, end = NULL, } if (length(threshold) == 1) { thres <- Apply(data, target_dims = dimensions, - fun = function(x) {quantile(as.vector(x), threshold, na.rm)})$output1 + fun = function(x) {quantile(as.vector(x), threshold, na.rm)})$output1 } else { thres <- Apply(data, target_dims = dimensions, - fun = function(x) {quantile(as.vector(x), threshold, na.rm)}, - output_dims = 'probs')$output1 + fun = function(x) {quantile(as.vector(x), threshold, na.rm)}, + output_dims = 'probs')$output1 } return(thres) } diff --git a/R/TotalSpellTimeExceedingThreshold.R b/R/TotalSpellTimeExceedingThreshold.R index 0ecbe9ef97ea4fe6ed57f7c1f08f330a8f42c31a..ac2261ae3380e12245fbbb705ac2535fa95fcc8e 100644 --- a/R/TotalSpellTimeExceedingThreshold.R +++ b/R/TotalSpellTimeExceedingThreshold.R @@ -1,34 +1,68 @@ #'Total Spell Time Exceeding Threshold #' -#'The number of days (when daily data is provided) that are part of a spell (defined by its minimum length e.g. 6 consecutive days) that exceed (or not exceed) a threshold are calculated with \code{TotalSpellTimeExceedingThreshold}. -#'This function allows to compute indicators widely used in Climate Services, such as: +#'The number of days (when daily data is provided) that are part of a spell +#'(defined by its minimum length e.g. 6 consecutive days) that exceed (or not +#'exceed) a threshold are calculated with \code{TotalSpellTimeExceedingThreshold}. +#'This function allows to compute indicators widely used in Climate Services, +#'such as: #'\itemize{ -#' \code{WSDI}{Warm Spell Duration Index that count the total number of days with at least 6 consecutive days when the daily temperature maximum exceeds its 90th percentile.}} -#'This function requires the data and the threshold to be in the same units. The 90th percentile can be translate into absolute values given a reference dataset using function \code{Threshold} or the data can be transform into probabilites by using function \code{AbsToProbs}. See section @examples. +#' \code{WSDI}{Warm Spell Duration Index that count the total number of days +#' with at least 6 consecutive days when the daily temperature +#' maximum exceeds its 90th percentile.} +#'} +#'This function requires the data and the threshold to be in the same units. The +#'90th percentile can be translate into absolute values given a reference dataset +#'using function \code{Threshold} or the data can be transform into probabilites +#'by using function \code{AbsToProbs}. See section @examples. #'@seealso [Threshold()] and [AbsToProbs()]. #' -#'@param data an 's2dv_cube' object as provided by function \code{CST_Load} in package CSTools. -#'@param threshold an 's2dv_cube' object as output of a 'CST_' function in the same units as parameter 'data' and with the common dimensions of the element 'data' of the same length. A single scalar is also possible. If \code{timd_dim} is in the dimension (with the same length as \code{data}), the comparison will be done day by day. -#'@param spell a scalar indicating the minimum length of the spell. -#'@param op a opartor '>' (by default), '<', '>=' or '<='. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data An 's2dv_cube' object as provided by function \code{CST_Load} in +#' package CSTools. +#'@param threshold An 's2dv_cube' object as output of a 'CST_' function in the +#' same units as parameter 'data' and with the common dimensions of the element +#' 'data' of the same length. A single scalar is also possible. If +#' \code{timd_dim} is in the dimension (with the same length as \code{data}), +#' the comparison will be done day by day. +#'@param spell A scalar indicating the minimum length of the spell. +#'@param op An operator '>' (by default), '<', '>=' or '<='. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the dimension to +#' compute the indicator. By default, it is set to 'ftime'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A 's2dv_cube' object containing the indicator in the element \code{data}. +#'@return An 's2dv_cube' object containing the indicator in the element +#'\code{data}. #' -#'@import multiApply #'@examples -#'exp <- CSTools::lonlat_data$exp -#'exp$data <- array(rnorm(5 * 3 * 20 * 2, mean = 25, sd = 3), -#' c(member = 5, sdate = 3, ftime = 20, lon = 2)) +#'exp <- NULL +#'exp$data <- array(rnorm(5 * 3 * 214 * 2)*23, +#' c(member = 5, sdate = 3, ftime = 214, lon = 2)) +#'exp$Dates$start <- c(seq(as.Date("01-05-2000", format = "%d-%m-%Y"), +#' as.Date("30-11-2000", format = "%d-%m-%Y"), by = 'day'), +#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), +#' as.Date("30-11-2001", format = "%d-%m-%Y"), by = 'day'), +#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), +#' as.Date("30-11-2002", format = "%d-%m-%Y"), by = 'day')) +#'class(exp) <- 's2dv_cube' #'TTSET <- CST_TotalSpellTimeExceedingThreshold(exp, threshold = 23, spell = 3) +#' +#'@import multiApply #'@export CST_TotalSpellTimeExceedingThreshold <- function(data, threshold, spell, op = '>', - start = NULL, end = NULL, - time_dim = 'ftime', - ncores = NULL) { + start = NULL, end = NULL, + time_dim = 'ftime', + ncores = NULL) { if (!inherits(data, 's2dv_cube')) { stop("Parameter 'data' must be of the class 's2dv_cube', ", "as output by CSTools::CST_Load.") @@ -41,20 +75,20 @@ CST_TotalSpellTimeExceedingThreshold <- function(data, threshold, spell, op = '> prod(dim(data$data)[time_dim] * dim(data$data)['sdate'])) { dim(data$Dates$start) <- c(dim(data$data)[time_dim], dim(data$data)['sdate']) + } else { + warning("Dimensions in 'data' element 'Dates$start' are missed and ", + "all data would be used.") } - } else { - warning("Dimensions in 'data' element 'Dates$start' are missed and", - "all data would be used.") } } - } - if (inherits(threshold, 's2dv_cube')) { + } + if (inherits(threshold, 's2dv_cube')) { threshold <- threshold$data } - total <- TotalSpellTimeExceedingThreshold(data$data, data$Dates[[1]], - threshold = threshold, spell = spell, op = op, - start = start, end = end, time_dim = time_dim, - ncores = ncores) + total <- TotalSpellTimeExceedingThreshold(data$data, data$Dates[[1]], + threshold = threshold, spell = spell, op = op, + start = start, end = end, time_dim = time_dim, + ncores = ncores) data$data <- total if (!is.null(start) && !is.null(end)) { data$Dates <- SelectPeriodOnDates(dates = data$Dates$start, @@ -65,31 +99,61 @@ CST_TotalSpellTimeExceedingThreshold <- function(data, threshold, spell, op = '> } #'Total Spell Time Exceeding Threshold #' -#'The number of days (when daily data is provided) that are part of a spell (defined by its minimum length e.g. 6 consecutive days) that exceed (or not exceed) a threshold are calculated with \code{TotalSpellTimeExceedingThreshold}. -#'This function allows to compute indicators widely used in Climate Services, such as: +#'The number of days (when daily data is provided) that are part of a spell +#'(defined by its minimum length e.g. 6 consecutive days) that exceed (or not +#'exceed) a threshold are calculated with \code{TotalSpellTimeExceedingThreshold}. +#'This function allows to compute indicators widely used in Climate Services, +#'such as: #'\itemize{ -#' \code{WSDI}{Warm Spell Duration Index that count the total number of days with at least 6 consecutive days when the daily temperature maximum exceeds its 90th percentile.}} -#'This function requires the data and the threshold to be in the same units. The 90th percentile can be translate into absolute values given a reference dataset using function \code{Threshold} or the data can be transform into probabilites by using function \code{AbsToProbs}. See section @examples. +#' \code{WSDI}{Warm Spell Duration Index that count the total number of days +#' with at least 6 consecutive days when the daily temperature +#' maximum exceeds its 90th percentile.} +#'} +#'This function requires the data and the threshold to be in the same units. The +#'90th percentile can be translate into absolute values given a reference +#'dataset using function \code{Threshold} or the data can be transform into +#'probabilites by using function \code{AbsToProbs}. See section @examples. #'@seealso [Threshold()] and [AbsToProbs()]. #' -#'@param data a multidimensional array with named dimensions. -#'@param threshold a multidimensional array with named dimensions in the same units as parameter 'data' and with the common dimensions of the element 'data' of the same length. If \code{timd_dim} is in the dimension (with the same length as \code{data}), the comparison will be done day by day. -#'@param spell a scalar indicating the minimum length of the spell. -#'@param op a opartor '>' (by default), '<', '>=' or '<='. -#'@param dates a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data A multidimensional array with named dimensions. +#'@param threshold A multidimensional array with named dimensions in the same +#' units as parameter 'data' and with the common dimensions of the element +#' 'data' of the same length. If \code{timd_dim} is in the dimension (with the +#' same length as \code{data}), the comparison will be done day by day. +#'@param spell A scalar indicating the minimum length of the spell. +#'@param op An operator '>' (by default), '<', '>=' or '<='. +#'@param dates A vector of dates or a multidimensional array of dates with named +#' dimensions matching the dimensions on parameter 'data'. By default it is +#' NULL, to select a period this parameter must be provided. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the dimension to +#' compute the indicator. By default, it is set to 'ftime'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A multidimensional array with named dimensions. +#'@return A multidimensional array with named dimensions containing the indicator +#'in the element \code{data}. #' -#'@details This function considers NA values as the end of the spell. For a different behaviour consider to modify the 'data' input by substituting NA values by values exceeding the threshold. -#'@import multiApply +#'@details This function considers NA values as the end of the spell. For a +#'different behaviour consider to modify the 'data' input by substituting NA +#'values by values exceeding the threshold. + #'@examples #'data <- array(rnorm(120), c(member = 1, sdate = 2, time = 20, lat = 4)) #'threshold <- array(rnorm(4), c(lat = 4)) #'total <- TotalSpellTimeExceedingThreshold(data, threshold, spell = 6) +#' +#'@import multiApply #'@export TotalSpellTimeExceedingThreshold <- function(data, threshold, spell, op = '>', dates = NULL, start = NULL, end = NULL, time_dim = 'time', @@ -105,7 +169,7 @@ TotalSpellTimeExceedingThreshold <- function(data, threshold, spell, op = '>', d names(dim(data)) <- time_dim } if (is.null(threshold)) { - stop("Parameter 'threshold' cannot be NULL.") + stop("Parameter 'threshold' cannot be NULL.") } if (!is.numeric(threshold)) { stop("Parameter 'threshold' must be numeric.") @@ -121,8 +185,8 @@ TotalSpellTimeExceedingThreshold <- function(data, threshold, spell, op = '>', d } if (time_dim %in% names(dim(threshold))) { if (dim(threshold)[time_dim] == dim(data)[time_dim]) { - threshold <- SelectPeriodOnData(threshold, dates, start, end, - time_dim = time_dim, ncores = ncores) + threshold <- SelectPeriodOnData(threshold, dates, start, end, + time_dim = time_dim, ncores = ncores) } } data <- SelectPeriodOnData(data, dates, start, end, @@ -148,9 +212,7 @@ TotalSpellTimeExceedingThreshold <- function(data, threshold, spell, op = '>', d } return(total) } -#data <- c(1,1,3,3,3,3,1,1,3,1,1,3,3,3,3,3) -#spell <- 3 -#threshold <- 2 + .totalspellthres <- function(data, threshold, spell, op = '>') { # data a time serie, threshold single value: if (op == '>') { diff --git a/R/TotalTimeExceedingThreshold.R b/R/TotalTimeExceedingThreshold.R index 3792caf90c2a26aeb6bec10cc92d5f4ddcfc0af5..ec25244d879adf3cd6d561e3b4aff5a6bc31bfbd 100644 --- a/R/TotalTimeExceedingThreshold.R +++ b/R/TotalTimeExceedingThreshold.R @@ -1,34 +1,68 @@ #'Total Time of a variable Exceeding (not exceeding) a Threshold #' -#'The Total Time of a variable exceeding (or not) a Threshold returns the total number of days -#'(if the data provided is daily, or the corresponding units to the data frequency provided) -#' that a variable is exceeding a threshold during a period. The threshold provided must be -#'in the same units than the variable units, i.e. to use a percentile as a scalar, -#'the function \code{AbsToProbs} or \code{QThreshold} may be needed (see examples). -#'Providing maximum temperature daily data, the following agriculture indices for heat stress can be obtained by using this function: +#'The Total Time of a variable exceeding (or not) a Threshold returns the total +#'number of days (if the data provided is daily, or the corresponding units to +#'the data frequency provided) that a variable is exceeding a threshold during a +#'period. The threshold provided must be in the same units than the variable +#'units, i.e. to use a percentile as a scalar, +#'the function \code{AbsToProbs} or \code{QThreshold} may be needed (see +#'examples). Providing maximum temperature daily data, the following agriculture +#'indices for heat stress can be obtained by using this function: #'\itemize{ -#' \item\code{SU35}{Total count of days when daily maximum temperatures exceed 35°C in the seven months from the start month given (e.g. from April to October for start month of April).} -#' \item\code{SU36}{Total count of days when daily maximum temperatures exceed 36 between June 21st and September 21st} -#' \item\code{SU40}{Total count of days when daily maximum temperatures exceed 40 between June 21st and September 21st} -#' \item\code{Spr32}{Total count of days when daily maximum temperatures exceed 32 between April 21st and June 21st} +#' \item\code{SU35}{Total count of days when daily maximum temperatures exceed +#' 35°C in the seven months from the start month given (e.g. +#' from April to October for start month of April).} +#' \item\code{SU36}{Total count of days when daily maximum temperatures exceed +#' 36 between June 21st and September 21st} +#' \item\code{SU40}{Total count of days when daily maximum temperatures exceed +#' 40 between June 21st and September 21st} +#' \item\code{Spr32}{Total count of days when daily maximum temperatures exceed +#' 32 between April 21st and June 21st} #'} #' -#'@param data a 's2dv_cube' object as provided by function \code{CST_Load} in package CSTools. -#'@param threshold a 's2dv_cube' object as output of a 'CST_' function in the same units as parameter \code{data} and with the common dimensions of the element \code{data} of the same length (e.g. an array with the same lengths of longitude and latitude). A single scalar is also possible (for the case of comparing all grid points with the same scalar). -#'@param op a opartor '>' (by default), '<', '>=' or '<='. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param na.rm a logical value indicating whether to ignore NA values (TRUE) or not (FALSE). -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data An 's2dv_cube' object as provided by function \code{CST_Load} in +#' package CSTools. +#'@param threshold An 's2dv_cube' object as output of a 'CST_' function in the +#' same units as parameter \code{data} and with the common dimensions of the +#' element \code{data} of the same length (e.g. an array with the same lengths +#' of longitude and latitude). A single scalar is also possible (for the case +#' of comparing all grid points with the same scalar). +#'@param op An operator '>' (by default), '<', '>=' or '<='. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the dimension to +#' compute the indicator. By default, it is set to 'ftime'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param na.rm A logical value indicating whether to ignore NA values (TRUE) or +#' not (FALSE). +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A 's2dv_cube' object containing the indicator in the element \code{data}. -#' -#'@import multiApply +#'@return An 's2dv_cube' object containing the indicator in the element +#'\code{data}. +#' #'@examples -#'exp <- CSTools::lonlat_data$exp -#'exp$data <- CSTools::lonlat_data$exp$data[1, 1, 3, 3, 1, 1] +#'exp <- NULL +#'exp$data <- array(abs(rnorm(5 * 3 * 214 * 2)*280), +#' c(member = 5, sdate = 3, ftime = 214, lon = 2)) +#'exp$Dates$start <- c(seq(as.Date("01-05-2000", format = "%d-%m-%Y"), +#' as.Date("30-11-2000", format = "%d-%m-%Y"), by = 'day'), +#' seq(as.Date("01-05-2001", format = "%d-%m-%Y"), +#' as.Date("30-11-2001", format = "%d-%m-%Y"), by = 'day'), +#' seq(as.Date("01-05-2002", format = "%d-%m-%Y"), +#' as.Date("30-11-2002", format = "%d-%m-%Y"), by = 'day')) +#'class(exp) <- 's2dv_cube' #'DOT <- CST_TotalTimeExceedingThreshold(exp, threshold = 280) +#' +#'@import multiApply #'@export CST_TotalTimeExceedingThreshold <- function(data, threshold, op = '>', start = NULL, end = NULL, @@ -46,20 +80,20 @@ CST_TotalTimeExceedingThreshold <- function(data, threshold, op = '>', prod(dim(data$data)[time_dim] * dim(data$data)['sdate'])) { dim(data$Dates$start) <- c(dim(data$data)[time_dim], dim(data$data)['sdate']) + } else { + warning("Dimensions in 'data' element 'Dates$start' are missed and ", + "all data would be used.") } - } else { - warning("Dimensions in 'data' element 'Dates$start' are missed and", - "all data would be used.") } } - } - if (inherits(threshold, 's2dv_cube')) { + } + if (inherits(threshold, 's2dv_cube')) { threshold <- threshold$data } - total <- TotalTimeExceedingThreshold(data$data, data$Dates[[1]], - threshold = threshold, op = op, - start = start, end = end, time_dim = time_dim, - na.rm = na.rm, ncores = ncores) + total <- TotalTimeExceedingThreshold(data$data, data$Dates[[1]], + threshold = threshold, op = op, + start = start, end = end, time_dim = time_dim, + na.rm = na.rm, ncores = ncores) data$data <- total if (!is.null(start) && !is.null(end)) { data$Dates <- SelectPeriodOnDates(dates = data$Dates$start, @@ -70,36 +104,62 @@ CST_TotalTimeExceedingThreshold <- function(data, threshold, op = '>', } #'Total Time of a variable Exceeding (not exceeding) a Threshold #' -#'The Total Time of a variable exceeding (or not) a Threshold returns the total number of days -#'(if the data provided is daily, or the corresponding units to the data frequency provided) -#' that a variable is exceeding a threshold during a period. The threshold provided must be -#'in the same units than the variable units, i.e. to use a percentile as a threshold, -#'the function \code{Threshold} or \code{QThreshold} may be needed (see examples). -#'Providing maximum temperature daily data, the following agriculture indices for heat stress can be obtained by using this function: +#'The Total Time of a variable exceeding (or not) a Threshold returns the total +#'number of days (if the data provided is daily, or the corresponding units to +#'the data frequency provided) that a variable is exceeding a threshold during a +#'period. The threshold provided must be in the same units than the variable +#'units, i.e. to use a percentile as a threshold, the function \code{Threshold} +#'or \code{QThreshold} may be needed (see examples). Providing maximum +#'temperature daily data, the following agriculture indices for heat stress can +#'be obtained by using this function: #'\itemize{ -#' \item\code{SU35}{Total count of days when daily maximum temperatures exceed 35°C} -#' \item\code{SU36}{Total count of days when daily maximum temperatures exceed 36 between June 21st and September 21st} -#' \item\code{SU40}{Total count of days when daily maximum temperatures exceed 40 between June 21st and September 21st} -#' \item\code{Spr32}{Total count of days when daily maximum temperatures exceed 32 between April 21st and June 21st} +#' \item\code{SU35}{Total count of days when daily maximum temperatures exceed +#' 35°C} +#' \item\code{SU36}{Total count of days when daily maximum temperatures exceed +#' 36 between June 21st and September 21st} +#' \item\code{SU40}{Total count of days when daily maximum temperatures exceed +#' 40 between June 21st and September 21st} +#' \item\code{Spr32}{Total count of days when daily maximum temperatures exceed +#' 32 between April 21st and June 21st} #'} #' -#'@param data a multidimensional array with named dimensions. -#'@param threshold a multidimensional array with named dimensions in the same units as parameter \code{data} and with the common dimensions of the element \code{data} of the same length (e.g. an array with the same lengths of longitude and latitude). A single scalar is also possible (for the case of comparing all grid points with the same scalar). -#'@param op a opartor '>' (by default), '<', '>=' or '<='. -#'@param dates a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the function to compute the indicator. By default, it is set to 'time'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param na.rm a logical value indicating whether to ignore NA values (TRUE) or not (FALSE). -#'@param ncores an integer indicating the number of cores to use in parallel computation. +#'@param data A multidimensional array with named dimensions. +#'@param threshold A multidimensional array with named dimensions in the same +#' units as parameter \code{data} and with the common dimensions of the element +#' \code{data} of the same length (e.g. an array with the same lengths of +#' longitude and latitude). A single scalar is also possible (for the case of +#' comparing all grid points with the same scalar). +#'@param op A operator '>' (by default), '<', '>=' or '<='. +#'@param dates A vector of dates or a multidimensional array of dates with named +#' dimensions matching the dimensions on parameter 'data'. By default it is +#' NULL, to select a period this parameter must be provided. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the dimension to +#' compute the indicator. By default, it is set to 'time'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param na.rm A logical value indicating whether to ignore NA values (TRUE) or +#' not (FALSE). +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation. #' -#'@return A multidimensional array with named dimensions. +#'@return A multidimensional array with named dimensions containing the +#'indicator in the element \code{data}. #' -#'@import multiApply #'@examples -#'exp <- CSTools::lonlat_data$exp$data[1, 5, 3, 3, 1, 1] +#'exp <- array(abs(rnorm(5 * 3 * 214 * 2)*280), +#' c(member = 5, sdate = 3, ftime = 214, lon = 2)) #'DOT <- TotalTimeExceedingThreshold(exp, threshold = 300, time_dim = 'ftime') #' +#'@import multiApply #'@export TotalTimeExceedingThreshold <- function(data, threshold, op = '>', dates = NULL, start = NULL, end = NULL, diff --git a/R/WindCapacityFactor.R b/R/WindCapacityFactor.R index 4b9bffb98363925a5d0afa65cde24276a83696a2..ee542ebe423fc54c57a114755e7905df9fa63214 100644 --- a/R/WindCapacityFactor.R +++ b/R/WindCapacityFactor.R @@ -1,26 +1,50 @@ #'Wind capacity factor on s2dv_cube objects #' #'@author Llorenç Lledó, \email{llledo@bsc.es} -#'@description Wind capacity factor computes the wind power generated by a specific wind turbine model under specific wind speed conditions, and expresses it as a fraction of the rated capacity (i.e. maximum power) of the turbine. -#'@description It is computed by means of a tabular power curve that relates wind speed to power output. The tabular values are interpolated with a linear piecewise approximating function to obtain a smooth power curve. Five different power curves that span different IEC classes can be selected (see below). -#'@references Lledó, Ll., Torralba, V., Soret, A., Ramon, J., & Doblas-Reyes, F. J. (2019). Seasonal forecasts of wind power generation. Renewable Energy, 143, 91–100. https://doi.org/10.1016/j.renene.2019.04.135 +#'@description Wind capacity factor computes the wind power generated by a +#'specific wind turbine model under specific wind speed conditions, and +#'expresses it as a fraction of the rated capacity (i.e. maximum power) of the +#'turbine. +#'@description It is computed by means of a tabular power curve that relates +#'wind speed to power output. The tabular values are interpolated with a linear +#'piecewise approximating function to obtain a smooth power curve. Five +#'different power curves that span different IEC classes can be selected (see +#'below). +#'@references Lledó, Ll., Torralba, V., Soret, A., Ramon, J., & Doblas-Reyes, F. J. (2019). +#'Seasonal forecasts of wind power generation. Renewable Energy, 143, 91–100. https://doi.org/10.1016/j.renene.2019.04.135 #'@references International Standard IEC 61400-1 (third ed.) (2005) #' -#'@param wind a s2dv_cube object with instantaneous wind speeds expressed in m/s. -#'@param IEC_class a string indicating the IEC wind class (see IEC 61400-1) of the turbine to be selected. Classes \code{'I'}, \code{'II'} and \code{'III'} are suitable for sites with an annual mean wind speed of 10, 8.5 and 7.5 m/s respectively. Classes \code{'I/II'} and \code{'II/III'} indicate intermediate turbines that fit both classes. More details of the five turbines and a plot of its power curves can be found in Lledó et al. (2019). -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param ncores an integer indicating the number of cores to use in parallel computation for temporal subsetting. -#'@return A s2dv_cube object containing the Wind Capacity Factor (unitless). +#'@param wind An s2dv_cube object with instantaneous wind speeds expressed in m/s. +#'@param IEC_class A string indicating the IEC wind class (see IEC 61400-1) of +#' the turbine to be selected. Classes \code{'I'}, \code{'II'} and \code{'III'} +#' are suitable for sites with an annual mean wind speed of 10, 8.5 and 7.5 m/s +#' respectively. Classes \code{'I/II'} and \code{'II/III'} indicate +#' intermediate turbines that fit both classes. More details of the five +#' turbines and a plot of its power curves can be found in Lledó et al. (2019). +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the dimension to +#' compute the indicator. By default, it is set to 'ftime'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation for temporal subsetting. +#'@return An s2dv_cube object containing the Wind Capacity Factor (unitless). #' #'@examples #'wind <- array(rweibull(n = 100, shape = 2, scale = 6), c(member = 10, lat = 2, lon = 5)) #'wind <- CSTools::s2dv_cube(data = wind, lat = c(40, 41), lon = 1:5, -#' Variable = list(varName = 'sfcWind', level = 'Surface'), -#' Datasets = 'synthetic', when = Sys.time(), -#' Dates = list(start = '1990-01-01 00:00:00', end = '1990-01-01 00:00:00'), -#' source_file = NA) +#' Variable = list(varName = 'sfcWind', level = 'Surface'), +#' Datasets = 'synthetic', when = Sys.time(), +#' Dates = list(start = '1990-01-01 00:00:00', end = '1990-01-01 00:00:00'), +#' source_file = NA) #'WCF <- CST_WindCapacityFactor(wind, IEC_class = "III") #' #'@export @@ -39,9 +63,10 @@ CST_WindCapacityFactor <- function(wind, IEC_class = c("I", "I/II", "II", "II/II prod(dim(wind$data)[time_dim] * dim(wind$data)['sdate'])) { dim(wind$Dates$start) <- c(dim(wind$data)[time_dim], dim(wind$data)['sdate']) + } else { + warning("Dimensions in 'data' element 'Dates$start' are missed and ", + "all data would be used.") } - } else { - warning("Dimensions in 'data' element 'Dates$start' are missed/unmatched. All data would be used.") } } } @@ -54,35 +79,63 @@ CST_WindCapacityFactor <- function(wind, IEC_class = c("I", "I/II", "II", "II/II } if (!is.null(start) && !is.null(end)) { wind$Dates <- SelectPeriodOnDates(dates = wind$Dates[[1]], - start = start, end = end, - time_dim = time_dim, ncores = ncores) + start = start, end = end, + time_dim = time_dim, ncores = ncores) } return(wind) } #'Wind capacity factor #' #'@author Llorenç Lledó, \email{llledo@bsc.es} -#'@description Wind capacity factor computes the wind power generated by a specific wind turbine model under specific wind speed conditions, and expresses it as a fraction of the rated capacity (i.e. maximum power) of the turbine. -#'@description It is computed by means of a tabular power curve that relates wind speed to power output. The tabular values are interpolated with a linear piecewise approximating function to obtain a smooth power curve. Five different power curves that span different IEC classes can be selected (see below). -#'@references Lledó, Ll., Torralba, V., Soret, A., Ramon, J., & Doblas-Reyes, F. J. (2019). Seasonal forecasts of wind power generation. Renewable Energy, 143, 91–100. https://doi.org/10.1016/j.renene.2019.04.135 +#'@description Wind capacity factor computes the wind power generated by a +#'specific wind turbine model under specific wind speed conditions, and +#'expresses it as a fraction of the rated capacity (i.e. maximum power) of the +#'turbine. +#'@description It is computed by means of a tabular power curve that relates +#'wind speed to power output. The tabular values are interpolated with a linear +#'piecewise approximating function to obtain a smooth power curve. Five +#'different power curves that span different IEC classes can be selected (see +#'below). +#'@references Lledó, Ll., Torralba, V., Soret, A., Ramon, J., & Doblas-Reyes, F. J. (2019). +#'Seasonal forecasts of wind power generation. Renewable Energy, 143, 91–100. https://doi.org/10.1016/j.renene.2019.04.135 #'@references International Standard IEC 61400-1 (third ed.) (2005) #' -#'@param wind a multidimensional array, vector or scalar with instantaneous wind speeds expressed in m/s. -#'@param IEC_class a string indicating the IEC wind class (see IEC 61400-1) of the turbine to be selected. Classes \code{'I'}, \code{'II'} and \code{'III'} are suitable for sites with an annual mean wind speed of 10, 8.5 and 7.5 m/s respectively. Classes \code{'I/II'} and \code{'II/III'} indicate intermediate turbines that fit both classes. More details of the five turbines and a plot of its power curves can be found in Lledó et al. (2019). -#'@param dates a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param ncores an integer indicating the number of cores to use in parallel computation for temporal subsetting. +#'@param wind A multidimensional array, vector or scalar with instantaneous wind +#' speeds expressed in m/s. +#'@param IEC_class A string indicating the IEC wind class (see IEC 61400-1) of +#' the turbine to be selected. Classes \code{'I'}, \code{'II'} and \code{'III'} +#' are suitable for sites with an annual mean wind speed of 10, 8.5 and 7.5 m/s +#' respectively. Classes \code{'I/II'} and \code{'II/III'} indicate +#' intermediate turbines that fit both classes. More details of the five +#' turbines and a plot of its power curves can be found in Lledó et al. (2019). +#'@param dates A vector of dates or a multidimensional array of dates with named +#' dimensions matching the dimensions on parameter 'data'. By default it is +#' NULL, to select a period this parameter must be provided. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the dimension to +#' compute the indicator. By default, it is set to 'ftime'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation for temporal subsetting. #' -#'@return An array with the same dimensions as wind, containing the Wind Capacity Factor (unitless). +#'@return An array with the same dimensions as wind, containing the Wind +#' Capacity Factor (unitless). #' -#'@importFrom stats approxfun -#'@importFrom utils read.delim #'@examples #'wind <- rweibull(n = 100, shape = 2, scale = 6) #'WCF <- WindCapacityFactor(wind, IEC_class = "III") #' +#'@importFrom stats approxfun +#'@importFrom utils read.delim #'@export WindCapacityFactor <- function(wind, IEC_class = c("I", "I/II", "II", "II/III", "III"), dates = NULL, start = NULL, end = NULL, diff --git a/R/WindPowerDensity.R b/R/WindPowerDensity.R index 1ecdc30236f5486143b1ebecd696f642924df3f1..bbdd07d87c6b82ce67544366ad042fe273051d99 100644 --- a/R/WindPowerDensity.R +++ b/R/WindPowerDensity.R @@ -1,25 +1,41 @@ #'Wind power density on s2dv_cube objects #' #'@author Llorenç Lledó, \email{llledo@bsc.es} -#'@description Wind Power Density computes the wind power that is available for extraction per square meter of swept area. -#'@description It is computed as 0.5*ro*wspd^3. As this function is non-linear, it will give inaccurate results if used with period means. +#'@description Wind Power Density computes the wind power that is available for +#'extraction per square meter of swept area. +#'@description It is computed as 0.5*ro*wspd^3. As this function is non-linear, +#'it will give inaccurate results if used with period means. #' -#'@param wind a s2dv_cube object with instantaneous wind speeds expressed in m/s obtained from CST_Load or s2dv_cube functions from CSTools pacakge -#'@param ro a scalar, or alternatively a multidimensional array with the same dimensions as wind, with the air density expressed in kg/m^3. By default it takes the value 1.225, the standard density of air at 15ºC and 1013.25 hPa. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param ncores an integer indicating the number of cores to use in parallel computation for temporal subsetting. +#'@param wind An s2dv_cube object with instantaneous wind speeds expressed in m/s +#' obtained from CST_Load or s2dv_cube functions from CSTools pacakge. +#'@param ro A scalar, or alternatively a multidimensional array with the same +#' dimensions as wind, with the air density expressed in kg/m^3. By default it +#' takes the value 1.225, the standard density of air at 15ºC and 1013.25 hPa. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the dimension to +#' compute the indicator. By default, it is set to 'ftime'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation for temporal subsetting. #' -#'@return A s2dv_cube object containing Wind Power Density expressed in W/m^2. +#'@return An s2dv_cube object containing Wind Power Density expressed in W/m^2. #' #'@examples #'wind <- array(rweibull(n = 100, shape = 2, scale = 6), c(member = 10, lat = 2, lon = 5)) #'wind <- CSTools::s2dv_cube(data = wind, lat = c(40, 41), lon = 1:5, -#' Variable = list(varName = 'sfcWind', level = 'Surface'), -#' Datasets = 'synthetic', when = Sys.time(), -#' Dates = list(start = '1990-01-01 00:00:00', end = '1990-01-01 00:00:00'), -#' source_file = NA) +#' Variable = list(varName = 'sfcWind', level = 'Surface'), +#' Datasets = 'synthetic', when = Sys.time(), +#' Dates = list(start = '1990-01-01 00:00:00', end = '1990-01-01 00:00:00'), +#' source_file = NA) #'WPD <- CST_WindPowerDensity(wind) #' #'@export @@ -37,9 +53,10 @@ CST_WindPowerDensity <- function(wind, ro = 1.225, start = NULL, end = NULL, prod(dim(wind$data)[time_dim] * dim(wind$data)['sdate'])) { dim(wind$Dates$start) <- c(dim(wind$data)[time_dim], dim(wind$data)['sdate']) + } else { + warning("Dimensions in 'data' element 'Dates$start' are missed and ", + "all data would be used.") } - } else { - warning("Dimensions in 'wind' element 'Dates$start' are missed/unmatched. All data would be used.") } } } @@ -52,8 +69,8 @@ CST_WindPowerDensity <- function(wind, ro = 1.225, start = NULL, end = NULL, } if (!is.null(start) && !is.null(end)) { wind$Dates <- SelectPeriodOnDates(dates = wind$Dates[[1]], - start = start, end = end, - time_dim = time_dim, ncores = ncores) + start = start, end = end, + time_dim = time_dim, ncores = ncores) } return(wind) } @@ -61,18 +78,37 @@ CST_WindPowerDensity <- function(wind, ro = 1.225, start = NULL, end = NULL, #'Wind power density on multidimensional array objects #' #'@author Llorenç Lledó, \email{llledo@bsc.es} -#'@description Wind Power Density computes the wind power that is available for extraction per square meter of swept area. -#'@description It is computed as 0.5*ro*wspd^3. As this function is non-linear, it will give inaccurate results if used with period means. +#'@description Wind Power Density computes the wind power that is available for +#'extraction per square meter of swept area. +#'@description It is computed as 0.5*ro*wspd^3. As this function is non-linear, +#'it will give inaccurate results if used with period means. #' -#'@param wind a multidimensional array, vector or scalar with instantaneous wind speeds expressed in m/s. -#'@param ro a scalar, or alternatively a multidimensional array with the same dimensions as wind, with the air density expressed in kg/m^3. By default it takes the value 1.225, the standard density of air at 15ºC and 1013.25 hPa. -#'@param dates a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided. -#'@param start an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param end an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}. -#'@param time_dim a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. -#'@param ncores an integer indicating the number of cores to use in parallel computation for temporal subsetting. +#'@param wind A multidimensional array, vector or scalar with instantaneous wind +#' speeds expressed in m/s. +#'@param ro A scalar, or alternatively a multidimensional array with the same +#' dimensions as wind, with the air density expressed in kg/m^3. By default it +#' takes the value 1.225, the standard density of air at 15ºC and 1013.25 hPa. +#'@param dates A vector of dates or a multidimensional array of dates with named +#' dimensions matching the dimensions on parameter 'data'. By default it is +#' NULL, to select a period this parameter must be provided. +#'@param start An optional parameter to defined the initial date of the period +#' to select from the data by providing a list of two elements: the initial +#' date of the period and the initial month of the period. By default it is set +#' to NULL and the indicator is computed using all the data provided in +#' \code{data}. +#'@param end An optional parameter to defined the final date of the period to +#' select from the data by providing a list of two elements: the final day of +#' the period and the final month of the period. By default it is set to NULL +#' and the indicator is computed using all the data provided in \code{data}. +#'@param time_dim A character string indicating the name of the dimension to +#' compute the indicator. By default, it is set to 'ftime'. More than one +#' dimension name matching the dimensions provided in the object +#' \code{data$data} can be specified. +#'@param ncores An integer indicating the number of cores to use in parallel +#' computation for temporal subsetting. #' -#'@return An array with the same dimensions as wind, containing Wind Power Density expressed in W/m^2. +#'@return An array with the same dimensions as wind, containing Wind Power +#'Density expressed in W/m^2. #' #'@examples #'wind <- rweibull(n = 100, shape = 2, scale = 6) diff --git a/R/zzz.R b/R/zzz.R index 35cd5a6b8f9deff819f5cea73a89e610f598fad9..52fa2cd557d0d25a7af8269cf46405db97a64359 100644 --- a/R/zzz.R +++ b/R/zzz.R @@ -5,13 +5,13 @@ position <- logical(length(dates)) if (ini_month != end_month) { pos <- sort(unique(c(pos[months == ini_month & days >= ini_day], - pos[months < end_month & months > ini_month], - pos[months == end_month & days <= end_day]))) + pos[months < end_month & months > ini_month], + pos[months == end_month & days <= end_day]))) position[pos] <- TRUE position[-pos] <- FALSE } else { pos <- sort(unique(c(pos[months == ini_month & - days >= ini_day & days <= end_day]))) + days >= ini_day & days <= end_day]))) position[pos] <- TRUE position[-pos] <- FALSE } diff --git a/README.md b/README.md index be122f6e243cd288c2a6ed5cacc40f26f0241c2f..2ed5fde1768871aefe4fef51b24a849563cafadc 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,73 @@ -# CSIndicators +CSIndicators +=============== -Sectorial Indicators for Climate Services: from sub-seasonal forecast to Decadal Predictions \ No newline at end of file +#### Sectoral Indicators for Climate Services Based on Sub-Seasonal to Decadal Climate Predictions + +## Description +Set of generalised tools for the flexible computation of climate related +indicators defined by the user. Each method represents a specific mathematical +approach which is combined with the possibility to select an arbitrary time +period to define the indicator. This enables a wide range of possibilities to +tailor the most suitable indicator for each particular climate service +application (agriculture, food security, energy, water management…). This package +is intended for sub-seasonal, seasonal and decadal climate predictions, but its +methods are also applicable to other time-scales, provided the dimensional +structure of the input is maintained. Additionally, the outputs of the functions +in this package are compatible with CSTools. + +## Functions and documentation + +To learn how to use the package see: + +- [**Agricultural Indicators**](https://CRAN.R-project.org/package=CSIndicators/vignettes/AgriculturalIndicators.html) +- [**Wind Energy Indicators**](https://CRAN.R-project.org/package=CSIndicators/vignettes/EnergyIndicators.html) + +Functions documentation can be found [here](https://CRAN.R-project.org/package=CSIndicators/CSIndicators.pdf) + +| Function | CST version | Indicators | +|--------------------------------|------------------------------------|---------------------------------| +|PeriodMean |CST_PeriodMean |GST, SprTX, DTR | +|PeriodAccumulation |CST_PeriodAccumulation |SprR, HarR, PRCPTOT | +|AccumulationExceedingThreshold |CST_AccumulationExceedingThreshold |GDD, R95pTOT, R99pTOT | +|TotalTimeExceedingThreshold |CST_TotalTimeExceedingThreshold |SU35, SU, FD, ID, TR, R10mm, Rnmm| +|TotalSpellTimeExceedingThreshold|CST_TotalSpellTimeExceedingThreshold|WSDI, CSDI | +|WindCapacityFactor |CST_WindCapacityFactor |Wind Capacity Factor | +|WindPowerDensity |CST_WindPowerDensity |Wind Power Density | + + +| Auxiliar function | CST version | +|-------------------|----------------------| +|AbsToProbs |CST_AbsToProbs | +|QThreshold |CST_QThreshold | +|Threshold |CST_Threshold | +|MergeRefToExp |CST_MergeRefToExp | +|SelectPeriodOnData |CST_SelectPeriodOnData| +|SelectPeriodOnDates| | + +Find the current status of each function in this link: https://docs.google.com/spreadsheets/d/1arqgw-etNPs-XRyMTJ4ekF5YjQxAZBzssxxr2GMXp3c/edit#gid=0. + +*Note: the CST version uses 's2dv_cube' objects as inputs and outputs while the former version uses multidimensional arrays with named dimensions as inputs and outputs* + +*Note: All functions computing indicators allows to subset a time period if required, although this temporal subsetting can also be done with functions `SelectPeriodOnData` in a separated step.* + + +### How to contribute + +1. Open an issue to ask for help or describe a function to be integrated +2. Agree with maintainers (@ngonzal2, @rmarcos, @nperez and @erifarov) on the requirements +3. Create a new branch from master with a meaningful name +4. Once the development is finished, open a merge request to merge the branch on master + +*Note: Remember to work with multidimensionals arrays with named dimensions when possible and use multiApply (https://earth.bsc.es/gitlab/ces/multiApply)* + +### Add a function + +To add a new function in this R package, follow this considerations: + +1. Each function exposed to the users should be in separate files in the R folder +2. The name of the function should match the name of the file (e.g.: `Function()` included in file **Function.R** +3. The documentation should be in roxygen2 format as a header of the function +4. Once, the function and the documentation is finished, run the command `devtools::document()` in your R terminal to automatically generate the **Function.Rd** file +5. Remember to use R 3.6.1 when doing the development +6. Code format: include spaces between operators (e.g. +, -, &), before { and after ','. The maximum length of lines is of 100 characters (hard limit 80 characters). Number of indentation spaces is 2. +7. Functions computing Climate indicators should include a temporal subsetting option. Use the already existing functions to adapt your code. diff --git a/man/AbsToProbs.Rd b/man/AbsToProbs.Rd index c4507a28e29d0cbb31b17abaebee0c4ffb279a92..9b79296bfa5b152c6c75bbac08b05bf33828a1ac 100644 --- a/man/AbsToProbs.Rd +++ b/man/AbsToProbs.Rd @@ -16,38 +16,59 @@ AbsToProbs( ) } \arguments{ -\item{data}{a multidimensional array with named dimensions.} +\item{data}{A multidimensional array with named dimensions.} -\item{dates}{a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided.} +\item{dates}{A vector of dates or a multidimensional array of dates with named +dimensions matching the dimensions on parameter 'data'. By default it is +NULL, to select a period this parameter must be provided.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to define the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to define the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the temporal dimension. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. This dimension is required to subset the data in a requested period.} +\item{time_dim}{A character string indicating the name of the temporal +dimension. By default, it is set to 'ftime'. More than one dimension name +matching the dimensions provided in the object \code{data$data} can be +specified. This dimension is required to subset the data in a requested +period.} -\item{memb_dim}{a character string indicating the name of the dimension in which the ensemble members are stored.} +\item{memb_dim}{A character string indicating the name of the dimension in +which the ensemble members are stored.} -\item{sdate_dim}{a character string indicating the name of the dimension in which the initialization dates are stored.} +\item{sdate_dim}{A character string indicating the name of the dimension in +which the initialization dates are stored.} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A multidimensional array with named dimensions. +A multidimensional array with named dimensions containing the +probabilites in the element \code{data}. } \description{ -The Cumulative Distribution Function of a forecast is used to obtain the probabilities of each value in the ensemble. If multiple initializations (start dates) are provided, the function will create the Cumulative Distribution Function excluding the corresponding initialization. +The Cumulative Distribution Function of a forecast is used to obtain the +probabilities of each value in the ensemble. If multiple initializations +(start dates) are provided, the function will create the Cumulative +Distribution Function excluding the corresponding initialization. } \examples{ -exp <- CSTools::lonlat_prec$data +exp <- array(rnorm(216), dim = c(dataset = 1, member = 2, sdate = 3, ftime = 9, lat = 2, lon = 2)) exp_probs <- AbsToProbs(exp) data <- array(rnorm(5 * 2 * 61 * 1), - c(member = 5, sdate = 2, ftime = 61, lon = 1)) + c(member = 5, sdate = 2, ftime = 61, lon = 1)) Dates <- c(seq(as.Date("01-05-2000", format = "\%d-\%m-\%Y"), - as.Date("30-06-2000", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), - as.Date("30-06-2001", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), - as.Date("30-06-2002", format = "\%d-\%m-\%Y"), by = 'day')) + as.Date("30-06-2000", format = "\%d-\%m-\%Y"), by = 'day'), + seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), + as.Date("30-06-2001", format = "\%d-\%m-\%Y"), by = 'day'), + seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), + as.Date("30-06-2002", format = "\%d-\%m-\%Y"), by = 'day')) exp_probs <- AbsToProbs(exp, start = list(21, 4), end = list(21, 6)) + } diff --git a/man/AccumulationExceedingThreshold.Rd b/man/AccumulationExceedingThreshold.Rd index 0dd414f7a476a9767de2c8b76da61d1c3d5e147e..e646dc627b325dece44c37eb14f72842f54998a8 100644 --- a/man/AccumulationExceedingThreshold.Rd +++ b/man/AccumulationExceedingThreshold.Rd @@ -18,36 +18,59 @@ AccumulationExceedingThreshold( ) } \arguments{ -\item{data}{a multidimensional array with named dimensions.} +\item{data}{A multidimensional array with named dimensions.} -\item{threshold}{a multidimensional array with named dimensions in the same units as parameter 'data' and with the common dimensions of the element 'data' of the same length.} +\item{threshold}{a multidimensional array with named dimensions in the same +units as parameter 'data' and with the common dimensions of the element +'data' of the same length.} -\item{op}{a opartor '>' (by default), '<', '>=' or '<='.} +\item{op}{An operator '>' (by default), '<', '>=' or '<='.} -\item{diff}{a logical value indicating whether to accumulate the difference between data and threshold (TRUE) or not (FALSE by default).} +\item{diff}{A logical value indicating whether to accumulate the difference +between data and threshold (TRUE) or not (FALSE by default).} -\item{dates}{a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided.} +\item{dates}{A vector of dates or a multidimensional array of dates with named +dimensions matching the dimensions on parameter 'data'. By default it is +NULL, to select a period this parameter must be provided.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute the indicator. By default, it is set to 'ftime'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{na.rm}{a logical value indicating whether to ignore NA values (TRUE) or not (FALSE).} +\item{na.rm}{A logical value indicating whether to ignore NA values (TRUE) or +not (FALSE).} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A multidimensional array with named dimensions. +A multidimensional array with named dimensions containing the +indicator in the element \code{data}. } \description{ -The accumulation (sum) of a variable in the days (or time steps) that the variable is exceeding (or not exceeding) a threshold during a period. The threshold provided must be -in the same units than the variable units, i.e. to use a percentile as a scalar, -the function \code{Threshold} or \code{QThreshold} may be needed. -Providing mean daily temperature data, the following agriculture indices for heat stress can be obtained by using this function: +The accumulation (sum) of a variable in the days (or time steps) that the +variable is exceeding (or not exceeding) a threshold during a period. The +threshold provided must be in the same units than the variable units, i.e. to +use a percentile as a scalar, the function \code{Threshold} or +\code{QThreshold} may be needed. Providing mean daily temperature data, the +following agriculture indices for heat stress can be obtained by using this +function: \itemize{ - \item\code{GDD}{Summation of daily differences between daily average temperatures and 10°C between April 1st and October 31st}} + \item\code{GDD}{Summation of daily differences between daily average + temperatures and 10°C between April 1st and October 31st} +} } \examples{ # Assuming data is already (tasmax + tasmin)/2 - 10 diff --git a/man/CST_AbsToProbs.Rd b/man/CST_AbsToProbs.Rd index ec1bd8fb659b29d001d29285bc7978c775e31c71..57426efb6f4e7e88f6c3618c5e89a3db31f0e8fd 100644 --- a/man/CST_AbsToProbs.Rd +++ b/man/CST_AbsToProbs.Rd @@ -15,36 +15,58 @@ CST_AbsToProbs( ) } \arguments{ -\item{data}{an 's2dv_cube' object as provided function \code{CST_Load} in package CSTools.} +\item{data}{An 's2dv_cube' object as provided function \code{CST_Load} in +package CSTools.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to define the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to define the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the temporal dimension. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. This dimension is required to subset the data in a requested period.} +\item{time_dim}{A character string indicating the name of the temporal +dimension. By default, it is set to 'ftime'. More than one dimension name +matching the dimensions provided in the object \code{data$data} can be +specified. This dimension is required to subset the data in a requested +period.} -\item{memb_dim}{a character string indicating the name of the dimension in which the ensemble members are stored.} +\item{memb_dim}{A character string indicating the name of the dimension in +which the ensemble members are stored.} -\item{sdate_dim}{a character string indicating the name of the dimension in which the initialization dates are stored.} +\item{sdate_dim}{A character string indicating the name of the dimension in +which the initialization dates are stored.} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A 's2dv_cube' object containing the probabilites in the element \code{data}. +An 's2dv_cube' object containing the probabilites in the element \code{data}. } \description{ -The Cumulative Distribution Function of a forecast is used to obtain the probabilities of each value in the ensemble. If multiple initializations (start dates) are provided, the function will create the Cumulative Distribution Function excluding the corresponding initialization. +The Cumulative Distribution Function of a forecast is used to obtain the +probabilities of each value in the ensemble. If multiple initializations +(start dates) are provided, the function will create the Cumulative +Distribution Function excluding the corresponding initialization. } \examples{ -exp <- CSTools::lonlat_prec +exp <- NULL +exp$data <- array(rnorm(216), dim = c(dataset = 1, member = 2, sdate = 3, + ftime = 9, lat = 2, lon = 2)) +class(exp) <- 's2dv_cube' exp_probs <- CST_AbsToProbs(exp) exp$data <- array(rnorm(5 * 3 * 214 * 2), - c(member = 5, sdate = 3, ftime = 214, lon = 2)) + c(member = 5, sdate = 3, ftime = 214, lon = 2)) exp$Dates[[1]] <- c(seq(as.Date("01-05-2000", format = "\%d-\%m-\%Y"), - as.Date("30-11-2000", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), - as.Date("30-11-2001", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), - as.Date("30-11-2002", format = "\%d-\%m-\%Y"), by = 'day')) + as.Date("30-11-2000", format = "\%d-\%m-\%Y"), by = 'day'), + seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), + as.Date("30-11-2001", format = "\%d-\%m-\%Y"), by = 'day'), + seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), + as.Date("30-11-2002", format = "\%d-\%m-\%Y"), by = 'day')) exp_probs <- CST_AbsToProbs(exp, start = list(21, 4), end = list(21, 6)) + } diff --git a/man/CST_AccumulationExceedingThreshold.Rd b/man/CST_AccumulationExceedingThreshold.Rd index 4fbcebc97ef68a855a66971c331ce974b9072d45..9c0a521ae8bda6a57e102060bb91804bdaf496e6 100644 --- a/man/CST_AccumulationExceedingThreshold.Rd +++ b/man/CST_AccumulationExceedingThreshold.Rd @@ -17,37 +17,61 @@ CST_AccumulationExceedingThreshold( ) } \arguments{ -\item{data}{a 's2dv_cube' object as provided by function \code{CST_Load} in package CSTools.} +\item{data}{An 's2dv_cube' object as provided by function \code{CST_Load} in +package CSTools.} -\item{threshold}{a 's2dv_cube' object as output of a 'CST_' function in the same units as parameter 'data' and with the common dimensions of the element 'data' of the same length. A single scalar is also possible.} +\item{threshold}{An 's2dv_cube' object as output of a 'CST_' function in the +same units as parameter 'data' and with the common dimensions of the element +'data' of the same length. A single scalar is also possible.} -\item{op}{a opartor '>' (by default), '<', '>=' or '<='.} +\item{op}{An operator '>' (by default), '<', '>=' or '<='.} -\item{diff}{a logical value indicating whether to accumulate the difference between data and threshold (TRUE) or not (FALSE by default).} +\item{diff}{A logical value indicating whether to accumulate the difference +between data and threshold (TRUE) or not (FALSE by default).} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute the indicator. By default, it is set to 'ftime'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{na.rm}{a logical value indicating whether to ignore NA values (TRUE) or not (FALSE).} +\item{na.rm}{A logical value indicating whether to ignore NA values (TRUE) or +not (FALSE).} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ A 's2dv_cube' object containing the indicator in the element \code{data}. } \description{ -The accumulation (sum) of a variable in the days (or time steps) that the variable is exceeding (or not exceeding) a threshold during a period. The threshold provided must be -in the same units than the variable units, i.e. to use a percentile as a scalar, -the function \code{Threshold} or \code{QThreshold} may be needed. -Providing mean daily temperature data, the following agriculture indices for heat stress can be obtained by using this function: +The accumulation (sum) of a variable in the days (or time steps) that the +variable is exceeding (or not exceeding) a threshold during a period. The +threshold provided must be in the same units than the variable units, i.e. to +use a percentile as a scalar, the function \code{Threshold} or +\code{QThreshold} may be needed. Providing mean daily temperature data, the +following agriculture indices for heat stress can be obtained by using this +function: \itemize{ - \item\code{GDD}{Summation of daily differences between daily average temperatures and 10°C between April 1st and October 31st}} + \item\code{GDD}{Summation of daily differences between daily average + temperatures and 10°C between April 1st and October 31st} +} } \examples{ -exp <- CSTools::lonlat_data$exp -exp$data <- CSTools::lonlat_data$exp$data[1, 5, 3, 3, 1, 1] +exp <- NULL +exp$data <- array(rnorm(216)*200, dim = c(dataset = 1, member = 2, sdate = 3, + ftime = 9, lat = 2, lon = 2)) +class(exp) <- 's2dv_cube' DOT <- CST_AccumulationExceedingThreshold(exp, threshold = 280) + } diff --git a/man/CST_MergeRefToExp.Rd b/man/CST_MergeRefToExp.Rd index 61c184048246628ed9c5e625f4d544771aec016d..a5b9cc76fa4e73595a865eac4998bc2c417b3772 100644 --- a/man/CST_MergeRefToExp.Rd +++ b/man/CST_MergeRefToExp.Rd @@ -17,29 +17,54 @@ CST_MergeRefToExp( ) } \arguments{ -\item{data1}{an 's2dv_cube' object as provided function \code{CST_Load} in package CSTools.} +\item{data1}{An 's2dv_cube' object as provided function \code{CST_Load} in +package CSTools.} -\item{data2}{an 's2dv_cube' object as provided function \code{CST_Load} in package CSTools.} +\item{data2}{An 's2dv_cube' object as provided function \code{CST_Load} in +package CSTools.} -\item{start1}{a list to defined the initial date of the period to select from data1 by providing a list of two elements: the initial date of the period and the initial month of the period.} +\item{start1}{A list to define the initial date of the period to select from +data1 by providing a list of two elements: the initial date of the period +and the initial month of the period.} -\item{end1}{a list to defined the final date of the period to select from data1 by providing a list of two elements: the final day of the period and the final month of the period.} +\item{end1}{A list to define the final date of the period to select from +data1 by providing a list of two elements: the final day of the period and +the final month of the period.} -\item{start2}{a list to defined the initial date of the period to select from data2 by providing a list of two elements: the initial date of the period and the initial month of the period.} +\item{start2}{A list to define the initial date of the period to select from +data2 by providing a list of two elements: the initial date of the period +and the initial month of the period.} -\item{end2}{a list to defined the final date of the period to select from data2 by providing a list of two elements: the final day of the period and the final month of the period.} +\item{end2}{A list to define the final date of the period to select from +data2 by providing a list of two elements: the final day of the period and +the final month of the period.} -\item{time_dim}{a character string indicating the name of the temporal dimension. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. This dimension is required to subset the data in a requested period.} +\item{time_dim}{A character string indicating the name of the temporal +dimension. By default, it is set to 'ftime'. More than one dimension name +matching the dimensions provided in the object \code{data$data} can be +specified. This dimension is required to subset the data in a requested period.} -\item{sdate_dim}{a character string indicating the name of the dimension in which the initialization dates are stored.} +\item{sdate_dim}{A character string indicating the name of the dimension in +which the initialization dates are stored.} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A 's2dv_cube' object containing the indicator in the element \code{data}. +A 's2dv_cube' object containing the indicator in the element + \code{data}. } \description{ -Some indicators are defined for specific temporal periods (e.g.: summer from June 21st to September 21st). If the initialization forecast date is later than the one required for the indicator (e.g.: July 1st), the user may want to merge past observations, or other references, to the forecast (or hindcast) to compute the indicator. The function \code{MergeObs2Exp} takes care of this steps. If the forecast simulation doesn't cover the required period because it is initialized too early (e.g.: Initialization on November 1st the forecast covers until the beginning of June next year), a climatology (or other references) could be added at the end of the forecast lead time to cover the desired period (e.g.: until the end of summer). +Some indicators are defined for specific temporal periods (e.g.: summer from +June 21st to September 21st). If the initialization forecast date is later +than the one required for the indicator (e.g.: July 1st), the user may want to +merge past observations, or other references, to the forecast (or hindcast) +to compute the indicator. The function \code{MergeObs2Exp} takes care of this +steps. If the forecast simulation doesn't cover the required period because it +is initialized too early (e.g.: Initialization on November 1st the forecast +covers until the beginning of June next year), a climatology (or other +references) could be added at the end of the forecast lead time to cover the +desired period (e.g.: until the end of summer). } \examples{ data_dates <- c(seq(as.Date("01-07-1993", "\%d-\%m-\%Y", tz = 'UTC'), @@ -47,16 +72,19 @@ data_dates <- c(seq(as.Date("01-07-1993", "\%d-\%m-\%Y", tz = 'UTC'), seq(as.Date("01-07-1994", "\%d-\%m-\%Y", tz = 'UTC'), as.Date("01-12-1994","\%d-\%m-\%Y", tz = 'UTC'), "day")) dim(data_dates) <- c(ftime = 154, sdate = 2) +data <- NULL +data$data <- array(1:(2*154*2), c(ftime = 154, sdate = 2, member= 2)) +data$Dates$start <- data_dates +class(data) <- 's2dv_cube' ref_dates <- seq(as.Date("01-01-1993", "\%d-\%m-\%Y", tz = 'UTC'), as.Date("01-12-1994","\%d-\%m-\%Y", tz = 'UTC'), "day") dim(ref_dates) <- c(ftime = 350, sdate = 2) -ref <- array(1001:1700, c(ftime = 350, sdate = 2)) -data <- array(1:(2*154*2), c(ftime = 154, sdate = 2, member= 2)) -ref <- CSTools::s2dv_cube(data = ref, Dates = list(start = ref_dates, - end = ref_dates)) -data <- CSTools::s2dv_cube(data = data, Dates = list(start = data_dates, - end = data_dates)) +ref <- NULL +ref$data <- array(1001:1700, c(ftime = 350, sdate = 2)) +ref$Dates$start <- ref_dates +class(ref) <- 's2dv_cube' new_data <- CST_MergeRefToExp(data1 = ref, data2 = data, start1 = list(21, 6), end1 = list(30, 6), start2 = list(1, 7), end2 = list(21, 9)) + } diff --git a/man/CST_PeriodAccumulation.Rd b/man/CST_PeriodAccumulation.Rd index 0337a136b7d2c5e5c063666f0fb58a22a0ed2c72..abc79b69cd51f8cce811885b0f17c134ce681187 100644 --- a/man/CST_PeriodAccumulation.Rd +++ b/man/CST_PeriodAccumulation.Rd @@ -14,43 +14,65 @@ CST_PeriodAccumulation( ) } \arguments{ -\item{data}{an 's2dv_cube' object as provided function \code{CST_Load} in package CSTools.} +\item{data}{An 's2dv_cube' object as provided function \code{CST_Load} in +package CSTools.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute the indicator. By default, it is set to 'ftime'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{na.rm}{a logical value indicating whether to ignore NA values (TRUE) or not (FALSE).} +\item{na.rm}{A logical value indicating whether to ignore NA values (TRUE) or +not (FALSE).} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A 's2dv_cube' object containing the indicator in the element \code{data}. +A 's2dv_cube' object containing the indicator in the element +\code{data}. } \description{ -Period Accumulation computes the sum (accumulation) of a given variable in a period. -Providing precipitation data, two agriculture indices can be obtained by using this function: +Period Accumulation computes the sum (accumulation) of a given variable in a +period. Providing precipitation data, two agriculture indices can be obtained +by using this function: \itemize{ - \item\code{SprR}{Spring Total Precipitation: The total precipitation from April 21th to June 21st} - \item\code{HarR}{Harvest Total Precipitation: The total precipitation from August 21st to October 21st}} + \item\code{SprR}{Spring Total Precipitation: The total precipitation from + April 21th to June 21st} + \item\code{HarR}{Harvest Total Precipitation: The total precipitation from + August 21st to October 21st} +} } \examples{ -exp <- CSTools::lonlat_prec +exp <- NULL +exp$data <- array(rnorm(216)*200, dim = c(dataset = 1, member = 2, sdate = 3, + ftime = 9, lat = 2, lon = 2)) +class(exp) <- 's2dv_cube' TP <- CST_PeriodAccumulation(exp) exp$data <- array(rnorm(5 * 3 * 214 * 2), c(memb = 5, sdate = 3, ftime = 214, lon = 2)) exp$Dates[[1]] <- c(seq(as.Date("01-05-2000", format = "\%d-\%m-\%Y"), - as.Date("30-11-2000", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), - as.Date("30-11-2001", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), - as.Date("30-11-2002", format = "\%d-\%m-\%Y"), by = 'day')) + as.Date("30-11-2000", format = "\%d-\%m-\%Y"), by = 'day'), + seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), + as.Date("30-11-2001", format = "\%d-\%m-\%Y"), by = 'day'), + seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), + as.Date("30-11-2002", format = "\%d-\%m-\%Y"), by = 'day')) SprR <- CST_PeriodAccumulation(exp, start = list(21, 4), end = list(21, 6)) dim(SprR$data) head(SprR$Dates) HarR <- CST_PeriodAccumulation(exp, start = list(21, 8), end = list(21, 10)) dim(HarR$data) head(HarR$Dates) + } diff --git a/man/CST_PeriodMean.Rd b/man/CST_PeriodMean.Rd index 1beefc5ff32ff195ba184c46a9ed748cc4d70028..b9ae538ee38a6bdd51e03fa09e7be58925211964 100644 --- a/man/CST_PeriodMean.Rd +++ b/man/CST_PeriodMean.Rd @@ -14,31 +14,54 @@ CST_PeriodMean( ) } \arguments{ -\item{data}{an 's2dv_cube' object as provided function \code{CST_Load} in package CSTools.} +\item{data}{An 's2dv_cube' object as provided function \code{CST_Load} in +package CSTools.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute the indicator. By default, it is set to 'ftime'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{na.rm}{a logical value indicating whether to ignore NA values (TRUE) or not (FALSE).} +\item{na.rm}{A logical value indicating whether to ignore NA values (TRUE) or +not (FALSE).} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A 's2dv_cube' object containing the indicator in the element \code{data}. +An 's2dv_cube' object containing the indicator in the element + \code{data}. } \description{ Period Mean computes the average (mean) of a given variable in a period. -Providing temperature data, two agriculture indices can be obtain by using this function: +Providing temperature data, two agriculture indices can be obtained by using +this function: \itemize{ - \item\code{GST}{Growing Season average Temperature: The average temperature from April 1st to Octobe 31st} - \item\code{SprTX}{Spring Average Maximum Temperature: The average daily maximum temperature from April 1st to May 31st}} + \item\code{GST}{Growing Season average Temperature: The average temperature + from April 1st to Octobe 31st} + \item\code{SprTX}{Spring Average Maximum Temperature: The average daily + maximum temperature from April 1st to May 31st} +} } \examples{ -exp <- CSTools::lonlat_data$exp -exp$data <- CSTools::lonlat_data$exp$data[1, , 3, , 1, 1] +exp <- NULL +exp$data <- array(rnorm(45), dim = c(member = 7, ftime = 8)) +class(exp) <- 's2dv_cube' +exp$Dates$start <- c(seq(as.Date("01-07-1993", "\%d-\%m-\%Y", tz = 'UTC'), + as.Date("01-08-1993","\%d-\%m-\%Y", tz = 'UTC'), "day"), + seq(as.Date("01-07-1994", "\%d-\%m-\%Y", tz = 'UTC'), + as.Date("01-08-1994","\%d-\%m-\%Y", tz = 'UTC'), "day")) SA <- CST_PeriodMean(exp) } diff --git a/man/CST_QThreshold.Rd b/man/CST_QThreshold.Rd index 744724aa88ec883524abef4a734f122317c15f76..0edbcba89a4e3a3ff57c7c5b4d090f6859c38185 100644 --- a/man/CST_QThreshold.Rd +++ b/man/CST_QThreshold.Rd @@ -16,48 +16,81 @@ CST_QThreshold( ) } \arguments{ -\item{data}{an 's2dv_cube' object as provided function \code{CST_Load} in package CSTools.} +\item{data}{An 's2dv_cube' object as provided function \code{CST_Load} in +package CSTools.} -\item{threshold}{an 's2dv_cube' object as output of a 'CST_' function in the same units as parameter 'data' and with the common dimensions of the element 'data' of the same length. A single scalar is also possible.} +\item{threshold}{An 's2dv_cube' object as output of a 'CST_' function in the +same units as parameter 'data' and with the common dimensions of the element +'data' of the same length. A single scalar is also possible.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the temporal dimension. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. This dimension is required to subset the data in a requested period.} +\item{time_dim}{A character string indicating the name of the temporal +dimension. By default, it is set to 'ftime'. More than one dimension name +matching the dimensions provided in the object \code{data$data} can be +specified. This dimension is required to subset the data in a requested +period.} -\item{memb_dim}{a character string indicating the name of the dimension in which the ensemble members are stored.} +\item{memb_dim}{A character string indicating the name of the dimension in +which the ensemble members are stored.} -\item{sdate_dim}{a character string indicating the name of the dimension in which the initialization dates are stored.} +\item{sdate_dim}{A character string indicating the name of the dimension in +which the initialization dates are stored.} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A 's2dv_cube' object containing the probabilites in the element \code{data}. +An 's2dv_cube' object containing the probability of an absolute +threshold in the element \code{data}. } \description{ -From a user perspective, an absolute threshold can be very useful for a specific needs (e.g.: grape variety). -However, this absolute threshold could be transform to a relative threshold in order to get its frequency in a given dataset. -Therefore, the function \code{QThreshold} returns the probability of an absolute threshold. -This is done by computing the Cumulative Distribution Function of a sample and leaving-one-ot. -The sample used will depend on the dimensions of the data provided and the dimension names provided in sdate_dim and memb_dim parameters: +From the user's perspective, an absolute threshold can be very useful for a +specific needs (e.g.: grape variety). However, this absolute threshold could +be transformed to a relative threshold in order to get its frequency in a given +dataset. Therefore, the function \code{QThreshold} returns the probability of +an absolute threshold. This is done by computing the Cumulative Distribution +Function of a sample and leaving one out. The sample used will depend on the +dimensions of the data provided and the dimension names provided in sdate_dim +and memb_dim parameters: +} +\details{ \itemize{ - \item{Wheter a forecast (hindcast) has dimensions member and start date, and both must be used in the sample, their names should be passed in sdate_dim and memb_dim.} - \item{Wheter a forecast (hindcast) has dimensions member and start date, and only start date must be used in the sample (the calculation is done in each separate member), memb_dim can be set to NULL.} - \item{Wheter a reference (observations) has start date dimension, the sample used is the start date dimension.} - \item{Wheter a reference (observations) doesn't have start date dimension, the sample used must be especified in sdate_dim parameter.}} + \item{If a forecast (hindcast) has dimensions member and start date, and + both must be used in the sample, their names should be passed in + sdate_dim and memb_dim.} + \item{If a forecast (hindcast) has dimensions member and start date, and + only start date must be used in the sample (the calculation is done in + each separate member), memb_dim can be set to NULL.} + \item{If a reference (observations) has start date dimension, the sample + used is the start date dimension.} + \item{If a reference (observations) doesn't have start date dimension, + the sample used must be especified in sdate_dim parameter.} +} } \examples{ threshold <- 26 -exp <- CSTools::lonlat_prec +exp <- NULL +exp$data <- array(abs(rnorm(112)*26), dim = c(member = 7, sdate = 8, ftime = 2)) +class(exp) <- 's2dv_cube' exp_probs <- CST_QThreshold(exp, threshold) exp$data <- array(rnorm(5 * 3 * 214 * 2), c(member = 5, sdate = 3, ftime = 214, lon = 2)) exp$Dates[[1]] <- c(seq(as.Date("01-05-2000", format = "\%d-\%m-\%Y"), - as.Date("30-11-2000", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), - as.Date("30-11-2001", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), - as.Date("30-11-2002", format = "\%d-\%m-\%Y"), by = 'day')) -exp_probs <- CST_QThreshold(exp, threshold, start = list(21, 4), end = list(21, 6)) + as.Date("30-11-2000", format = "\%d-\%m-\%Y"), by = 'day'), + seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), + as.Date("30-11-2001", format = "\%d-\%m-\%Y"), by = 'day'), + seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), + as.Date("30-11-2002", format = "\%d-\%m-\%Y"), by = 'day')) +exp_probs <- CST_QThreshold(exp, threshold) + } diff --git a/man/CST_SelectPeriodOnData.Rd b/man/CST_SelectPeriodOnData.Rd index 2bac4182945cc2a22df20757ab1114193d932672..6e041624af16a773bbfa7a32a6a06ca55aca3f60 100644 --- a/man/CST_SelectPeriodOnData.Rd +++ b/man/CST_SelectPeriodOnData.Rd @@ -7,31 +7,43 @@ CST_SelectPeriodOnData(data, start, end, time_dim = "ftime", ncores = NULL) } \arguments{ -\item{data}{an 's2dv_cube' object as provided function \code{CST_Load} in package CSTools.} +\item{data}{An 's2dv_cube' object as provided function \code{CST_Load} in +package CSTools.} -\item{start}{a parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period.} +\item{start}{A parameter to defined the initial date of the period to select +from the data by providing a list of two elements: the initial date of the +period and the initial month of the period.} -\item{end}{a parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period.} +\item{end}{A parameter to defined the final date of the period to select from +the data by providing a list of two elements: the final day of the period +and the final month of the period.} -\item{time_dim}{a character string indicating the name of the dimension to compute select the dates. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute select the dates. By default, it is set to 'ftime'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A 's2dv_cube' object containing the subset of the object \code{data$data} during the period requested from \code{start} to \code{end}. +A 's2dv_cube' object containing the subset of the object +\code{data$data} during the period requested from \code{start} to \code{end}. } \description{ Auxiliary function to subset data for a specific period. } \examples{ -exp <- CSTools::lonlat_prec +exp <- NULL exp$data <- array(rnorm(5 * 3 * 214 * 2), - c(memb = 5, sdate = 3, ftime = 214, lon = 2)) -exp$Dates[[1]] <- c(seq(as.Date("01-05-2000", format = "\%d-\%m-\%Y"), - as.Date("30-11-2000", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), - as.Date("30-11-2001", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), - as.Date("30-11-2002", format = "\%d-\%m-\%Y"), by = 'day')) + c(memb = 5, sdate = 3, ftime = 214, lon = 2)) +exp$Dates$start <- c(seq(as.Date("01-05-2000", format = "\%d-\%m-\%Y"), + as.Date("30-11-2000", format = "\%d-\%m-\%Y"), by = 'day'), + seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), + as.Date("30-11-2001", format = "\%d-\%m-\%Y"), by = 'day'), + seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), + as.Date("30-11-2002", format = "\%d-\%m-\%Y"), by = 'day')) +class(exp) <- 's2dv_cube' Period <- CST_SelectPeriodOnData(exp, start = list(21, 6), end = list(21, 9)) + } diff --git a/man/CST_Threshold.Rd b/man/CST_Threshold.Rd index bff93fa02f40b70111feb0785de243bb378d5d93..5d260e9cb656f205a5d67339b573fdfd1627285b 100644 --- a/man/CST_Threshold.Rd +++ b/man/CST_Threshold.Rd @@ -17,42 +17,64 @@ CST_Threshold( ) } \arguments{ -\item{data}{an 's2dv_cube' object as provided function \code{CST_Load} in package CSTools.} +\item{data}{An 's2dv_cube' object as provided function \code{CST_Load} in +package CSTools.} -\item{threshold}{a single scalar or vector indicating the relative threshold(s).} +\item{threshold}{A single scalar or vector indicating the relative +threshold(s).} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to selectfrom the data by providing a list of two elements: the initial date +of the period and the initial month of the period. By default it is set to +NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the temporal dimension. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. This dimension is required to subset the data in a requested period.} +\item{time_dim}{A character string indicating the name of the temporal +dimension. By default, it is set to 'ftime'. More than one dimension name +matching the dimensions provided in the object \code{data$data} can be +specified. This dimension is required to subset the data in a requested +period.} -\item{memb_dim}{a character string indicating the name of the dimension in which the ensemble members are stored. When set it to NULL, threshold is computed for individual members.} +\item{memb_dim}{A character string indicating the name of the dimension in +which the ensemble members are stored. When set it to NULL, threshold is +computed for individual members.} -\item{sdate_dim}{a character string indicating the name of the dimension in which the initialization dates are stored.} +\item{sdate_dim}{A character string indicating the name of the dimension in +which the initialization dates are stored.} -\item{na.rm}{a logical value indicating whether to ignore NA values (TRUE) or not (FALSE).} +\item{na.rm}{A logical value indicating whether to ignore NA values (TRUE) or +not (FALSE).} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A 's2dv_cube' object containing the probabilites in the element \code{data}. +An ’s2dv_cube’ object containing the corresponding values of a +percentile in the element \code{data}. } \description{ -Frequently, thresholds are defined by a percentile that may correspond to a different absolute value depending on the variable, gridpoint and also julian day (time). -This function calculates the corresponding value of a percentile given a dataset. +Frequently, thresholds are defined by a percentile that may correspond to a +different absolute value depending on the variable, gridpoint and also julian +day (time). This function calculates the corresponding value of a percentile +given a dataset. } \examples{ threshold <- 0.9 -exp <- CSTools::lonlat_prec -exp_probs <- CST_Threshold(exp, threshold) +exp <- NULL exp$data <- array(rnorm(5 * 3 * 214 * 2), c(member = 5, sdate = 3, ftime = 214, lon = 2)) -exp$Dates[[1]] <- c(seq(as.Date("01-05-2000", format = "\%d-\%m-\%Y"), - as.Date("30-11-2000", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), - as.Date("30-11-2001", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), - as.Date("30-11-2002", format = "\%d-\%m-\%Y"), by = 'day')) +exp$Dates$start <- c(seq(as.Date("01-05-2000", format = "\%d-\%m-\%Y"), + as.Date("30-11-2000", format = "\%d-\%m-\%Y"), by = 'day'), + seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), + as.Date("30-11-2001", format = "\%d-\%m-\%Y"), by = 'day'), + seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), + as.Date("30-11-2002", format = "\%d-\%m-\%Y"), by = 'day')) +class(exp) <- 's2dv_cube' exp_probs <- CST_Threshold(exp, threshold, start = list(21, 4), end = list(21, 6)) + } diff --git a/man/CST_TotalSpellTimeExceedingThreshold.Rd b/man/CST_TotalSpellTimeExceedingThreshold.Rd index 8e65e5827b9e6998ddabefa54420883ffa65dea6..847fed25a2a4a66c22b918f3e7c23b2ea84833b6 100644 --- a/man/CST_TotalSpellTimeExceedingThreshold.Rd +++ b/man/CST_TotalSpellTimeExceedingThreshold.Rd @@ -16,37 +16,71 @@ CST_TotalSpellTimeExceedingThreshold( ) } \arguments{ -\item{data}{an 's2dv_cube' object as provided by function \code{CST_Load} in package CSTools.} +\item{data}{An 's2dv_cube' object as provided by function \code{CST_Load} in +package CSTools.} -\item{threshold}{an 's2dv_cube' object as output of a 'CST_' function in the same units as parameter 'data' and with the common dimensions of the element 'data' of the same length. A single scalar is also possible. If \code{timd_dim} is in the dimension (with the same length as \code{data}), the comparison will be done day by day.} +\item{threshold}{An 's2dv_cube' object as output of a 'CST_' function in the +same units as parameter 'data' and with the common dimensions of the element +'data' of the same length. A single scalar is also possible. If +\code{timd_dim} is in the dimension (with the same length as \code{data}), +the comparison will be done day by day.} -\item{spell}{a scalar indicating the minimum length of the spell.} +\item{spell}{A scalar indicating the minimum length of the spell.} -\item{op}{a opartor '>' (by default), '<', '>=' or '<='.} +\item{op}{An operator '>' (by default), '<', '>=' or '<='.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute the indicator. By default, it is set to 'ftime'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A 's2dv_cube' object containing the indicator in the element \code{data}. +An 's2dv_cube' object containing the indicator in the element +\code{data}. } \description{ -The number of days (when daily data is provided) that are part of a spell (defined by its minimum length e.g. 6 consecutive days) that exceed (or not exceed) a threshold are calculated with \code{TotalSpellTimeExceedingThreshold}. -This function allows to compute indicators widely used in Climate Services, such as: +The number of days (when daily data is provided) that are part of a spell +(defined by its minimum length e.g. 6 consecutive days) that exceed (or not +exceed) a threshold are calculated with \code{TotalSpellTimeExceedingThreshold}. +This function allows to compute indicators widely used in Climate Services, +such as: \itemize{ -\code{WSDI}{Warm Spell Duration Index that count the total number of days with at least 6 consecutive days when the daily temperature maximum exceeds its 90th percentile.}} -This function requires the data and the threshold to be in the same units. The 90th percentile can be translate into absolute values given a reference dataset using function \code{Threshold} or the data can be transform into probabilites by using function \code{AbsToProbs}. See section @examples. +\code{WSDI}{Warm Spell Duration Index that count the total number of days + with at least 6 consecutive days when the daily temperature + maximum exceeds its 90th percentile.} +} +This function requires the data and the threshold to be in the same units. The +90th percentile can be translate into absolute values given a reference dataset +using function \code{Threshold} or the data can be transform into probabilites +by using function \code{AbsToProbs}. See section @examples. } \examples{ -exp <- CSTools::lonlat_data$exp -exp$data <- array(rnorm(5 * 3 * 20 * 2, mean = 25, sd = 3), - c(member = 5, sdate = 3, ftime = 20, lon = 2)) +exp <- NULL +exp$data <- array(rnorm(5 * 3 * 214 * 2)*23, + c(member = 5, sdate = 3, ftime = 214, lon = 2)) +exp$Dates$start <- c(seq(as.Date("01-05-2000", format = "\%d-\%m-\%Y"), + as.Date("30-11-2000", format = "\%d-\%m-\%Y"), by = 'day'), + seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), + as.Date("30-11-2001", format = "\%d-\%m-\%Y"), by = 'day'), + seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), + as.Date("30-11-2002", format = "\%d-\%m-\%Y"), by = 'day')) +class(exp) <- 's2dv_cube' TTSET <- CST_TotalSpellTimeExceedingThreshold(exp, threshold = 23, spell = 3) + } \seealso{ [Threshold()] and [AbsToProbs()]. diff --git a/man/CST_TotalTimeExceedingThreshold.Rd b/man/CST_TotalTimeExceedingThreshold.Rd index e1d3c7ddfd08cdcc9a12dbe77d8952697dfcb40f..bbd05e04b7091c524e7468a754644d5c21ba3e1b 100644 --- a/man/CST_TotalTimeExceedingThreshold.Rd +++ b/man/CST_TotalTimeExceedingThreshold.Rd @@ -16,41 +16,75 @@ CST_TotalTimeExceedingThreshold( ) } \arguments{ -\item{data}{a 's2dv_cube' object as provided by function \code{CST_Load} in package CSTools.} +\item{data}{An 's2dv_cube' object as provided by function \code{CST_Load} in +package CSTools.} -\item{threshold}{a 's2dv_cube' object as output of a 'CST_' function in the same units as parameter \code{data} and with the common dimensions of the element \code{data} of the same length (e.g. an array with the same lengths of longitude and latitude). A single scalar is also possible (for the case of comparing all grid points with the same scalar).} +\item{threshold}{An 's2dv_cube' object as output of a 'CST_' function in the +same units as parameter \code{data} and with the common dimensions of the +element \code{data} of the same length (e.g. an array with the same lengths +of longitude and latitude). A single scalar is also possible (for the case +of comparing all grid points with the same scalar).} -\item{op}{a opartor '>' (by default), '<', '>=' or '<='.} +\item{op}{An operator '>' (by default), '<', '>=' or '<='.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute the indicator. By default, it is set to 'ftime'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{na.rm}{a logical value indicating whether to ignore NA values (TRUE) or not (FALSE).} +\item{na.rm}{A logical value indicating whether to ignore NA values (TRUE) or +not (FALSE).} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A 's2dv_cube' object containing the indicator in the element \code{data}. +An 's2dv_cube' object containing the indicator in the element +\code{data}. } \description{ -The Total Time of a variable exceeding (or not) a Threshold returns the total number of days -(if the data provided is daily, or the corresponding units to the data frequency provided) -that a variable is exceeding a threshold during a period. The threshold provided must be -in the same units than the variable units, i.e. to use a percentile as a scalar, -the function \code{AbsToProbs} or \code{QThreshold} may be needed (see examples). -Providing maximum temperature daily data, the following agriculture indices for heat stress can be obtained by using this function: +The Total Time of a variable exceeding (or not) a Threshold returns the total +number of days (if the data provided is daily, or the corresponding units to +the data frequency provided) that a variable is exceeding a threshold during a +period. The threshold provided must be in the same units than the variable +units, i.e. to use a percentile as a scalar, +the function \code{AbsToProbs} or \code{QThreshold} may be needed (see +examples). Providing maximum temperature daily data, the following agriculture +indices for heat stress can be obtained by using this function: \itemize{ - \item\code{SU35}{Total count of days when daily maximum temperatures exceed 35°C in the seven months from the start month given (e.g. from April to October for start month of April).} - \item\code{SU36}{Total count of days when daily maximum temperatures exceed 36 between June 21st and September 21st} - \item\code{SU40}{Total count of days when daily maximum temperatures exceed 40 between June 21st and September 21st} - \item\code{Spr32}{Total count of days when daily maximum temperatures exceed 32 between April 21st and June 21st} + \item\code{SU35}{Total count of days when daily maximum temperatures exceed + 35°C in the seven months from the start month given (e.g. + from April to October for start month of April).} + \item\code{SU36}{Total count of days when daily maximum temperatures exceed + 36 between June 21st and September 21st} + \item\code{SU40}{Total count of days when daily maximum temperatures exceed + 40 between June 21st and September 21st} + \item\code{Spr32}{Total count of days when daily maximum temperatures exceed + 32 between April 21st and June 21st} } } \examples{ -exp <- CSTools::lonlat_data$exp -exp$data <- CSTools::lonlat_data$exp$data[1, 1, 3, 3, 1, 1] +exp <- NULL +exp$data <- array(abs(rnorm(5 * 3 * 214 * 2)*280), + c(member = 5, sdate = 3, ftime = 214, lon = 2)) +exp$Dates$start <- c(seq(as.Date("01-05-2000", format = "\%d-\%m-\%Y"), + as.Date("30-11-2000", format = "\%d-\%m-\%Y"), by = 'day'), + seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), + as.Date("30-11-2001", format = "\%d-\%m-\%Y"), by = 'day'), + seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), + as.Date("30-11-2002", format = "\%d-\%m-\%Y"), by = 'day')) +class(exp) <- 's2dv_cube' DOT <- CST_TotalTimeExceedingThreshold(exp, threshold = 280) + } diff --git a/man/CST_WindCapacityFactor.Rd b/man/CST_WindCapacityFactor.Rd index 9e0a46cdafa9c6c69ae316248e4b7b60f17fd6cc..1dd879bebefc4f8675f0549a7f38ba8efc6d116c 100644 --- a/man/CST_WindCapacityFactor.Rd +++ b/man/CST_WindCapacityFactor.Rd @@ -14,38 +14,62 @@ CST_WindCapacityFactor( ) } \arguments{ -\item{wind}{a s2dv_cube object with instantaneous wind speeds expressed in m/s.} +\item{wind}{An s2dv_cube object with instantaneous wind speeds expressed in m/s.} -\item{IEC_class}{a string indicating the IEC wind class (see IEC 61400-1) of the turbine to be selected. Classes \code{'I'}, \code{'II'} and \code{'III'} are suitable for sites with an annual mean wind speed of 10, 8.5 and 7.5 m/s respectively. Classes \code{'I/II'} and \code{'II/III'} indicate intermediate turbines that fit both classes. More details of the five turbines and a plot of its power curves can be found in Lledó et al. (2019).} +\item{IEC_class}{A string indicating the IEC wind class (see IEC 61400-1) of +the turbine to be selected. Classes \code{'I'}, \code{'II'} and \code{'III'} +are suitable for sites with an annual mean wind speed of 10, 8.5 and 7.5 m/s +respectively. Classes \code{'I/II'} and \code{'II/III'} indicate +intermediate turbines that fit both classes. More details of the five +turbines and a plot of its power curves can be found in Lledó et al. (2019).} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute the indicator. By default, it is set to 'ftime'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{ncores}{an integer indicating the number of cores to use in parallel computation for temporal subsetting.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation for temporal subsetting.} } \value{ -A s2dv_cube object containing the Wind Capacity Factor (unitless). +An s2dv_cube object containing the Wind Capacity Factor (unitless). } \description{ -Wind capacity factor computes the wind power generated by a specific wind turbine model under specific wind speed conditions, and expresses it as a fraction of the rated capacity (i.e. maximum power) of the turbine. +Wind capacity factor computes the wind power generated by a +specific wind turbine model under specific wind speed conditions, and +expresses it as a fraction of the rated capacity (i.e. maximum power) of the +turbine. -It is computed by means of a tabular power curve that relates wind speed to power output. The tabular values are interpolated with a linear piecewise approximating function to obtain a smooth power curve. Five different power curves that span different IEC classes can be selected (see below). +It is computed by means of a tabular power curve that relates +wind speed to power output. The tabular values are interpolated with a linear +piecewise approximating function to obtain a smooth power curve. Five +different power curves that span different IEC classes can be selected (see +below). } \examples{ wind <- array(rweibull(n = 100, shape = 2, scale = 6), c(member = 10, lat = 2, lon = 5)) wind <- CSTools::s2dv_cube(data = wind, lat = c(40, 41), lon = 1:5, - Variable = list(varName = 'sfcWind', level = 'Surface'), - Datasets = 'synthetic', when = Sys.time(), - Dates = list(start = '1990-01-01 00:00:00', end = '1990-01-01 00:00:00'), - source_file = NA) + Variable = list(varName = 'sfcWind', level = 'Surface'), + Datasets = 'synthetic', when = Sys.time(), + Dates = list(start = '1990-01-01 00:00:00', end = '1990-01-01 00:00:00'), + source_file = NA) WCF <- CST_WindCapacityFactor(wind, IEC_class = "III") } \references{ -Lledó, Ll., Torralba, V., Soret, A., Ramon, J., & Doblas-Reyes, F. J. (2019). Seasonal forecasts of wind power generation. Renewable Energy, 143, 91–100. https://doi.org/10.1016/j.renene.2019.04.135 +Lledó, Ll., Torralba, V., Soret, A., Ramon, J., & Doblas-Reyes, F. J. (2019). +Seasonal forecasts of wind power generation. Renewable Energy, 143, 91–100. https://doi.org/10.1016/j.renene.2019.04.135 International Standard IEC 61400-1 (third ed.) (2005) } diff --git a/man/CST_WindPowerDensity.Rd b/man/CST_WindPowerDensity.Rd index 8033bfe6c108d0d33c1b215a5d3bf14b9491775d..9c3040cbd6adfc0ed2ab4c8b05087976c0775d0e 100644 --- a/man/CST_WindPowerDensity.Rd +++ b/man/CST_WindPowerDensity.Rd @@ -14,33 +14,49 @@ CST_WindPowerDensity( ) } \arguments{ -\item{wind}{a s2dv_cube object with instantaneous wind speeds expressed in m/s obtained from CST_Load or s2dv_cube functions from CSTools pacakge} +\item{wind}{An s2dv_cube object with instantaneous wind speeds expressed in m/s +obtained from CST_Load or s2dv_cube functions from CSTools pacakge.} -\item{ro}{a scalar, or alternatively a multidimensional array with the same dimensions as wind, with the air density expressed in kg/m^3. By default it takes the value 1.225, the standard density of air at 15ºC and 1013.25 hPa.} +\item{ro}{A scalar, or alternatively a multidimensional array with the same +dimensions as wind, with the air density expressed in kg/m^3. By default it +takes the value 1.225, the standard density of air at 15ºC and 1013.25 hPa.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute the indicator. By default, it is set to 'ftime'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{ncores}{an integer indicating the number of cores to use in parallel computation for temporal subsetting.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation for temporal subsetting.} } \value{ -A s2dv_cube object containing Wind Power Density expressed in W/m^2. +An s2dv_cube object containing Wind Power Density expressed in W/m^2. } \description{ -Wind Power Density computes the wind power that is available for extraction per square meter of swept area. +Wind Power Density computes the wind power that is available for +extraction per square meter of swept area. -It is computed as 0.5*ro*wspd^3. As this function is non-linear, it will give inaccurate results if used with period means. +It is computed as 0.5*ro*wspd^3. As this function is non-linear, +it will give inaccurate results if used with period means. } \examples{ wind <- array(rweibull(n = 100, shape = 2, scale = 6), c(member = 10, lat = 2, lon = 5)) wind <- CSTools::s2dv_cube(data = wind, lat = c(40, 41), lon = 1:5, - Variable = list(varName = 'sfcWind', level = 'Surface'), - Datasets = 'synthetic', when = Sys.time(), - Dates = list(start = '1990-01-01 00:00:00', end = '1990-01-01 00:00:00'), - source_file = NA) + Variable = list(varName = 'sfcWind', level = 'Surface'), + Datasets = 'synthetic', when = Sys.time(), + Dates = list(start = '1990-01-01 00:00:00', end = '1990-01-01 00:00:00'), + source_file = NA) WPD <- CST_WindPowerDensity(wind) } diff --git a/man/MergeRefToExp.Rd b/man/MergeRefToExp.Rd index 9826df72f9201e23c327ae9a965378b101b3682f..f5b4958adcef5cf0d37cec9f8d03fc621dd79113 100644 --- a/man/MergeRefToExp.Rd +++ b/man/MergeRefToExp.Rd @@ -19,33 +19,53 @@ MergeRefToExp( ) } \arguments{ -\item{data1}{a multidimensional array with named dimensions.} +\item{data1}{A multidimensional array with named dimensions.} -\item{dates1}{a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data1'.} +\item{dates1}{a vector of dates or a multidimensional array of dates with +named dimensions matching the dimensions on parameter 'data1'.} -\item{start1}{a list to defined the initial date of the period to select from data1 by providing a list of two elements: the initial date of the period and the initial month of the period.} +\item{start1}{A list to define the initial date of the period to select from +data1 by providing a list of two elements: the initial date of the period +and the initial month of the period.} -\item{end1}{a list to defined the final date of the period to select from data1 by providing a list of two elements: the final day of the period and the final month of the period.} +\item{end1}{A list to define the final date of the period to select from +data1 by providing a list of two elements: the final day of the period and +the final month of the period.} -\item{data2}{a multidimensional array with named dimensions.} +\item{data2}{A multidimensional array with named dimensions.} -\item{dates2}{a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data2'.} +\item{dates2}{A vector of dates or a multidimensional array of dates with +named dimensions matching the dimensions on parameter 'data2'.} -\item{start2}{a list to defined the initial date of the period to select from data2 by providing a list of two elements: the initial date of the period and the initial month of the period.} +\item{start2}{A list to define the initial date of the period to select from +data2 by providing a list of two elements: the initial date of the period +and the initial month of the period.} -\item{end2}{a list to defined the final date of the period to select from data2 by providing a list of two elements: the final day of the period and the final month of the period.} +\item{end2}{A list to define the final date of the period to select from +data2 by providing a list of two elements: the final day of the period and +the final month of the period.} -\item{time_dim}{a character string indicating the name of the temporal dimension. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. This dimension is required to subset the data in a requested period.} +\item{time_dim}{A character string indicating the name of the temporal +dimension. By default, it is set to 'ftime'. More than one dimension name +matching the dimensions provided in the object \code{data$data} can be +specified. This dimension is required to subset the data in a requested period.} -\item{sdate_dim}{a character string indicating the name of the dimension in which the initialization dates are stored.} +\item{sdate_dim}{A character string indicating the name of the dimension in +which the initialization dates are stored.} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ A multidimensional array with named dimensions. } \description{ -Some indicators are defined for specific temporal periods (e.g.: summer from June 21st to September 21st). If the initialization forecast date is later than the one required for the indicator (e.g.: July 1st), the user may want to merge past observations, or other reference, to the forecast (or hindcast) to compute the indicator. The function \code{MergeObs2Exp} takes care of this steps. +Some indicators are defined for specific temporal periods (e.g.: summer from +June 21st to September 21st). If the initialization forecast date is later +than the one required for the indicator (e.g.: July 1st), the user may want to +merge past observations, or other reference, to the forecast (or hindcast) to +compute the indicator. The function \code{MergeObs2Exp} takes care of this +steps. } \examples{ data_dates <- c(seq(as.Date("01-07-1993", "\%d-\%m-\%Y", tz = 'UTC'), @@ -61,4 +81,5 @@ data <- array(1:(2*154*2), c(time = 154, sdate = 2, member= 2)) new_data <- MergeRefToExp(data1 = ref, dates1 = ref_dates, start1 = list(21, 6), end1 = list(30, 6), data2 = data, dates2 = data_dates, start2 = list(1, 7), end = list(21, 9)) + } diff --git a/man/PeriodAccumulation.Rd b/man/PeriodAccumulation.Rd index fbc225a1b68d2918055164d6d3b22b34a5841d07..99033211af06dc55c429d728d69c2fbee910c756 100644 --- a/man/PeriodAccumulation.Rd +++ b/man/PeriodAccumulation.Rd @@ -15,42 +15,63 @@ PeriodAccumulation( ) } \arguments{ -\item{data}{a multidimensional array with named dimensions.} +\item{data}{A multidimensional array with named dimensions.} -\item{dates}{a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided.} +\item{dates}{A vector of dates or a multidimensional array of dates with named +dimensions matching the dimensions on parameter 'data'. By default it is +NULL, to select a period this parameter must be provided.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the function to compute the indicator. By default, it is set to 'time'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute the indicator. By default, it is set to 'time'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{na.rm}{a logical value indicating whether to ignore NA values (TRUE) or not (FALSE).} +\item{na.rm}{A logical value indicating whether to ignore NA values (TRUE) or +not (FALSE).} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A multidimensional array with named dimensions. +A multidimensional array with named dimensions containing the +indicator in the element \code{data}. } \description{ -Period Accumulation computes the sum (accumulation) of a given variable in a period. -Providing precipitation data, two agriculture indices can be obtained by using this function: +Period Accumulation computes the sum (accumulation) of a given variable in a +period. Providing precipitation data, two agriculture indices can be obtained +by using this function: \itemize{ - \item\code{SprR}{Spring Total Precipitation: The total precipitation from April 21th to June 21st} - \item\code{HarR}{Harvest Total Precipitation: The total precipitation from August 21st to October 21st}} + \item\code{SprR}{Spring Total Precipitation: The total precipitation from + April 21th to June 21st} + \item\code{HarR}{Harvest Total Precipitation: The total precipitation from + August 21st to October 21st} +} } \examples{ -exp <- CSTools::lonlat_prec$data +exp <- array(rnorm(216)*200, dim = c(dataset = 1, member = 2, sdate = 3, + ftime = 9, lat = 2, lon = 2)) TP <- PeriodAccumulation(exp, time_dim = 'ftime') data <- array(rnorm(5 * 3 * 214 * 2), c(memb = 5, sdate = 3, time = 214, lon = 2)) # ftime tested Dates <- c(seq(as.Date("01-05-2000", format = "\%d-\%m-\%Y"), as.Date("30-11-2000", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), + seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), as.Date("30-11-2001", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), + seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), as.Date("30-11-2002", format = "\%d-\%m-\%Y"), by = 'day')) SprR <- PeriodAccumulation(data, dates = Dates, start = list(21, 4), end = list(21, 6)) HarR <- PeriodAccumulation(data, dates = Dates, start = list(21, 8), end = list(21, 10)) + } diff --git a/man/PeriodMean.Rd b/man/PeriodMean.Rd index 6062daa437dadd3ec1c5cfbc748bb7f53c2853ae..fffb332299a35a3a67e7fe274059628d592e7d5a 100644 --- a/man/PeriodMean.Rd +++ b/man/PeriodMean.Rd @@ -15,31 +15,51 @@ PeriodMean( ) } \arguments{ -\item{data}{a multidimensional array with named dimensions.} +\item{data}{A multidimensional array with named dimensions.} -\item{dates}{a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided.} +\item{dates}{A vector of dates or a multidimensional array of dates with named +dimensions matching the dimensions on parameter 'data'. By default it is +NULL, to select a period this parameter must be provided.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute the indicator. By default, it is set to 'ftime'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{na.rm}{a logical value indicating whether to ignore NA values (TRUE) or not (FALSE).} +\item{na.rm}{A logical value indicating whether to ignore NA values (TRUE) or +not (FALSE).} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A multidimensional array with named dimensions. +A multidimensional array with named dimensions containing the +indicator in the element \code{data}. } \description{ Period Mean computes the average (mean) of a given variable in a period. -Providing temperature data, two agriculture indices can be obtain by using this function: +Providing temperature data, two agriculture indices can be obtained by using +this function: \itemize{ - \item\code{GST}{Growing Season average Temperature: The average temperature from April 1st to Octobe 31st} - \item\code{SprTX}{Spring Average Maximum Temperature: The average daily maximum temperature from April 1st to May 31st}} + \item\code{GST}{Growing Season average Temperature: The average + temperature from April 1st to Octobe 31st} + \item\code{SprTX}{Spring Average Maximum Temperature: The average daily + maximum temperature from April 1st to May 31st} +} } \examples{ -exp <- CSTools::lonlat_prec$data +exp <- array(rnorm(56), dim = c(member = 7, ftime = 8)) SA <- PeriodMean(exp, time_dim = 'ftime') + } diff --git a/man/QThreshold.Rd b/man/QThreshold.Rd index ff4900ebef82fa930dae133c3ec1f5dff420cb82..2af6e5f93df4ae8e374bdb6211f531d94546ff47 100644 --- a/man/QThreshold.Rd +++ b/man/QThreshold.Rd @@ -17,42 +17,72 @@ QThreshold( ) } \arguments{ -\item{data}{a multidimensional array with named dimensions.} +\item{data}{A multidimensional array with named dimensions.} -\item{threshold}{a multidimensional array with named dimensions in the same units as parameter 'data' and with the common dimensions of the element 'data' of the same length.} +\item{threshold}{A multidimensional array with named dimensions in the same +units as parameter 'data' and with the common dimensions of the element +'data' of the same length.} -\item{dates}{a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided.} +\item{dates}{A vector of dates or a multidimensional array of dates with named +dimensions matching the dimensions on parameter 'data'. By default it is +NULL, to select a period this parameter must be provided.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the temporal dimension. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. This dimension is required to subset the data in a requested period.} +\item{time_dim}{A character string indicating the name of the temporal +dimension. By default, it is set to 'ftime'. More than one dimension name +matching the dimensions provided in the object \code{data$data} can be +specified. This dimension is required to subset the data in a requested +period.} -\item{memb_dim}{a character string indicating the name of the dimension in which the ensemble members are stored.} +\item{memb_dim}{A character string indicating the name of the dimension in +which the ensemble members are stored.} -\item{sdate_dim}{a character string indicating the name of the dimension in which the initialization dates are stored.} +\item{sdate_dim}{A character string indicating the name of the dimension in +which the initialization dates are stored.} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A multidimensional array with named dimensions. +A multidimensional array with named dimensions containing the +probability of an absolute threshold in the element \code{data}. } \description{ -From a user perspective, an absolute threshold can be very useful for a specific needs (e.g.: grape variety). -However, this absolute threshold could be transform to a relative threshold in order to get its frequency in a given dataset. -Therefore, the function \code{QThreshold} returns the probability of an absolute threshold. -This is done by computing the Cumulative Distribution Function of a sample and leaving-one-ot. -The sample used will depend on the dimensions of the data provided and the dimension names provided in sdate_dim and memb_dim parameters: +From the user's perspective, an absolute threshold can be very useful for a +specific needs (e.g.: grape variety). However, this absolute threshold could +be transformed to a relative threshold in order to get its frequency in a given +dataset. Therefore, the function \code{QThreshold} returns the probability of +an absolute threshold. This is done by computing the Cumulative Distribution +Function of a sample and leaving-one-ot. The sample used will depend on the +dimensions of the data provided and the dimension names provided in sdate_dim +and memb_dim parameters: \itemize{ - \item{Wheter a forecast (hindcast) has dimensions member and start date, and both must be used in the sample, their names should be passed in sdate_dim and memb_dim.} - \item{Wheter a forecast (hindcast) has dimensions member and start date, and only start date must be used in the sample (the calculation is done in each separate member), memb_dim can be set to NULL.} - \item{Wheter a reference (observations) has start date dimension, the sample used is the start date dimension.} - \item{Wheter a reference (observations) doesn't have start date dimension, the sample used must be especified in sdate_dim parameter.}} + \item{If a forecast (hindcast) has dimensions member and start date, and + both must be used in the sample, their names should be passed in + sdate_dim and memb_dim.} + \item{If a forecast (hindcast) has dimensions member and start date, and + only start date must be used in the sample (the calculation is done in + each separate member), memb_dim can be set to NULL.} + \item{If a reference (observations) has start date dimension, the sample + used is the start date dimension.} + \item{If a reference (observations) doesn't have start date dimension, + the sample used must be especified in sdate_dim parameter.} +} } \examples{ threshold = 25 data <- array(rnorm(5 * 3 * 20 * 2, mean = 26), c(member = 5, sdate = 3, time = 20, lon = 2)) thres_q <- QThreshold(data, threshold) + } diff --git a/man/SelectPeriodOnData.Rd b/man/SelectPeriodOnData.Rd index dabb190a10ecb7bf7f85176eddf5483657e00761..118cb98e2a1347e31bdb1603588c7ae5821767ea 100644 --- a/man/SelectPeriodOnData.Rd +++ b/man/SelectPeriodOnData.Rd @@ -7,32 +7,43 @@ SelectPeriodOnData(data, dates, start, end, time_dim = "ftime", ncores = NULL) } \arguments{ -\item{data}{a multidimensional array with named dimensions.} +\item{data}{A multidimensional array with named dimensions.} -\item{dates}{a vector of dates or a multidimensional array of dates with named dimensions.} +\item{dates}{A vector of dates or a multidimensional array of dates with named +dimensions.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period.} -\item{time_dim}{a character string indicating the name of the dimension to compute select the dates. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute select the dates. By default, it is set to 'ftime'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A multidimensional array with named dimensions. +A multidimensional array with named dimensions containing the subset +of the object \code{data} during the period requested from \code{start} to +\code{end}. } \description{ Auxiliary function to subset data for a specific period. } \examples{ data <- array(rnorm(5 * 3 * 214 * 2), - c(memb = 5, sdate = 3, ftime = 214, lon = 2)) + c(memb = 5, sdate = 3, ftime = 214, lon = 2)) Dates <- c(seq(as.Date("01-05-2000", format = "\%d-\%m-\%Y"), as.Date("30-11-2000", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), + seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), as.Date("30-11-2001", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), + seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), as.Date("30-11-2002", format = "\%d-\%m-\%Y"), by = 'day')) dim(Dates) <- c(ftime = 214, sdate = 3) Period <- SelectPeriodOnData(data, Dates, start = list(21, 6), end = list(21, 9)) diff --git a/man/SelectPeriodOnDates.Rd b/man/SelectPeriodOnDates.Rd index 2cd553ac529bbea5bbe6f140e4a4f13fd346fdc3..cce8e55d82776129dc3eda6f97d928534780869e 100644 --- a/man/SelectPeriodOnDates.Rd +++ b/man/SelectPeriodOnDates.Rd @@ -7,18 +7,28 @@ SelectPeriodOnDates(dates, start, end, time_dim = "ftime", ncores = NULL) } \arguments{ -\item{dates}{a vector of dates or a multidimensional array of dates with named dimensions.} +\item{dates}{A vector of dates or a multidimensional array of dates with named +dimensions.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period.} -\item{time_dim}{a character string indicating the name of the dimension to compute select the dates. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute select the dates. By default, it is set to 'ftime'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A multidimensional array with named dimensions. +A multidimensional array with named dimensions containing the subset of +the vector dates during the period requested from \code{start} to \code{end}. } \description{ Auxiliary function to subset dates for a specific period. @@ -26,9 +36,9 @@ Auxiliary function to subset dates for a specific period. \examples{ Dates <- c(seq(as.Date("01-05-2000", format = "\%d-\%m-\%Y"), as.Date("30-11-2000", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), + seq(as.Date("01-05-2001", format = "\%d-\%m-\%Y"), as.Date("30-11-2001", format = "\%d-\%m-\%Y"), by = 'day'), - seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), + seq(as.Date("01-05-2002", format = "\%d-\%m-\%Y"), as.Date("30-11-2002", format = "\%d-\%m-\%Y"), by = 'day')) Period <- SelectPeriodOnDates(Dates, start = list(21, 6), end = list(21, 9)) } diff --git a/man/Threshold.Rd b/man/Threshold.Rd index c2f3872c25d77bd4f7a6a1a1ddd6fd30ac7d229d..db5981753e68504c918674c79c85f87fd2847450 100644 --- a/man/Threshold.Rd +++ b/man/Threshold.Rd @@ -18,32 +18,54 @@ Threshold( ) } \arguments{ -\item{data}{a multidimensional array with named dimensions.} +\item{data}{A multidimensional array with named dimensions.} -\item{threshold}{a single scalar or vector indicating the relative threshold(s).} +\item{threshold}{A single scalar or vector indicating the relative +threshold(s).} -\item{dates}{a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided.} +\item{dates}{A vector of dates or a multidimensional array of dates with named +dimensions matching the dimensions on parameter 'data'. By default it is +NULL, to select a period this parameter must be provided.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the temporal dimension. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified. This dimension is required to subset the data in a requested period.} +\item{time_dim}{A character string indicating the name of the temporal +dimension. By default, it is set to 'ftime'. More than one dimension name +matching the dimensions provided in the object \code{data$data} can be +specified. This dimension is required to subset the data in a requested +period.} -\item{memb_dim}{a character string indicating the name of the dimension in which the ensemble members are stored. When set it to NULL, threshold is computed for individual members.} +\item{memb_dim}{A character string indicating the name of the dimension in +which the ensemble members are stored. When set it to NULL, threshold is +computed for individual members.} -\item{sdate_dim}{a character string indicating the name of the dimension in which the initialization dates are stored.} +\item{sdate_dim}{A character string indicating the name of the dimension in +which the initialization dates are stored.} -\item{na.rm}{a logical value indicating whether to ignore NA values (TRUE) or not (FALSE).} +\item{na.rm}{A logical value indicating whether to ignore NA values (TRUE) or +not (FALSE).} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A multidimensional array with named dimensions. +A multidimensional array with named dimensions containing the +corresponding values of a percentile in the element \code{data}. } \description{ -Frequently, thresholds are defined by a percentile that may correspond to a different absolute value depending on the variable, gridpoint and also julian day (time). -This function calculates the corresponding value of a percentile given a dataset. +Frequently, thresholds are defined by a percentile that may correspond to a +different absolute value depending on the variable, gridpoint and also julian +day (time). This function calculates the corresponding value of a percentile +given a dataset. } \examples{ threshold <- 0.9 @@ -52,4 +74,5 @@ data <- array(rnorm(25 * 3 * 214 * 2, mean = 26), thres_q <- Threshold(data, threshold) data <- array(rnorm(1 * 3 * 214 * 2), c(member = 1, sdate = 3, time = 214, lon = 2)) res <- Threshold(data, threshold) + } diff --git a/man/TotalSpellTimeExceedingThreshold.Rd b/man/TotalSpellTimeExceedingThreshold.Rd index bbbfe357c65818e3eff3e50e9ed64609192a50bf..37fd6cc0999f4bcf793bfa8da81248aa3758e87a 100644 --- a/man/TotalSpellTimeExceedingThreshold.Rd +++ b/man/TotalSpellTimeExceedingThreshold.Rd @@ -17,41 +17,70 @@ TotalSpellTimeExceedingThreshold( ) } \arguments{ -\item{data}{a multidimensional array with named dimensions.} +\item{data}{A multidimensional array with named dimensions.} -\item{threshold}{a multidimensional array with named dimensions in the same units as parameter 'data' and with the common dimensions of the element 'data' of the same length. If \code{timd_dim} is in the dimension (with the same length as \code{data}), the comparison will be done day by day.} +\item{threshold}{A multidimensional array with named dimensions in the same +units as parameter 'data' and with the common dimensions of the element +'data' of the same length. If \code{timd_dim} is in the dimension (with the +same length as \code{data}), the comparison will be done day by day.} -\item{spell}{a scalar indicating the minimum length of the spell.} +\item{spell}{A scalar indicating the minimum length of the spell.} -\item{op}{a opartor '>' (by default), '<', '>=' or '<='.} +\item{op}{An operator '>' (by default), '<', '>=' or '<='.} -\item{dates}{a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided.} +\item{dates}{A vector of dates or a multidimensional array of dates with named +dimensions matching the dimensions on parameter 'data'. By default it is +NULL, to select a period this parameter must be provided.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute the indicator. By default, it is set to 'ftime'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A multidimensional array with named dimensions. +A multidimensional array with named dimensions containing the indicator +in the element \code{data}. } \description{ -The number of days (when daily data is provided) that are part of a spell (defined by its minimum length e.g. 6 consecutive days) that exceed (or not exceed) a threshold are calculated with \code{TotalSpellTimeExceedingThreshold}. -This function allows to compute indicators widely used in Climate Services, such as: +The number of days (when daily data is provided) that are part of a spell +(defined by its minimum length e.g. 6 consecutive days) that exceed (or not +exceed) a threshold are calculated with \code{TotalSpellTimeExceedingThreshold}. +This function allows to compute indicators widely used in Climate Services, +such as: \itemize{ -\code{WSDI}{Warm Spell Duration Index that count the total number of days with at least 6 consecutive days when the daily temperature maximum exceeds its 90th percentile.}} -This function requires the data and the threshold to be in the same units. The 90th percentile can be translate into absolute values given a reference dataset using function \code{Threshold} or the data can be transform into probabilites by using function \code{AbsToProbs}. See section @examples. +\code{WSDI}{Warm Spell Duration Index that count the total number of days + with at least 6 consecutive days when the daily temperature + maximum exceeds its 90th percentile.} +} +This function requires the data and the threshold to be in the same units. The +90th percentile can be translate into absolute values given a reference +dataset using function \code{Threshold} or the data can be transform into +probabilites by using function \code{AbsToProbs}. See section @examples. } \details{ -This function considers NA values as the end of the spell. For a different behaviour consider to modify the 'data' input by substituting NA values by values exceeding the threshold. +This function considers NA values as the end of the spell. For a +different behaviour consider to modify the 'data' input by substituting NA +values by values exceeding the threshold. } \examples{ data <- array(rnorm(120), c(member = 1, sdate = 2, time = 20, lat = 4)) threshold <- array(rnorm(4), c(lat = 4)) total <- TotalSpellTimeExceedingThreshold(data, threshold, spell = 6) + } \seealso{ [Threshold()] and [AbsToProbs()]. diff --git a/man/TotalTimeExceedingThreshold.Rd b/man/TotalTimeExceedingThreshold.Rd index 855ef869f4818c6da3e31644c94c36bdc35ed69d..f874b50a3eac4e58a3d15ca287fe782c7e8c8176 100644 --- a/man/TotalTimeExceedingThreshold.Rd +++ b/man/TotalTimeExceedingThreshold.Rd @@ -17,43 +17,69 @@ TotalTimeExceedingThreshold( ) } \arguments{ -\item{data}{a multidimensional array with named dimensions.} +\item{data}{A multidimensional array with named dimensions.} -\item{threshold}{a multidimensional array with named dimensions in the same units as parameter \code{data} and with the common dimensions of the element \code{data} of the same length (e.g. an array with the same lengths of longitude and latitude). A single scalar is also possible (for the case of comparing all grid points with the same scalar).} +\item{threshold}{A multidimensional array with named dimensions in the same +units as parameter \code{data} and with the common dimensions of the element +\code{data} of the same length (e.g. an array with the same lengths of +longitude and latitude). A single scalar is also possible (for the case of +comparing all grid points with the same scalar).} -\item{op}{a opartor '>' (by default), '<', '>=' or '<='.} +\item{op}{A operator '>' (by default), '<', '>=' or '<='.} -\item{dates}{a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided.} +\item{dates}{A vector of dates or a multidimensional array of dates with named +dimensions matching the dimensions on parameter 'data'. By default it is +NULL, to select a period this parameter must be provided.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the function to compute the indicator. By default, it is set to 'time'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute the indicator. By default, it is set to 'time'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{na.rm}{a logical value indicating whether to ignore NA values (TRUE) or not (FALSE).} +\item{na.rm}{A logical value indicating whether to ignore NA values (TRUE) or +not (FALSE).} -\item{ncores}{an integer indicating the number of cores to use in parallel computation.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation.} } \value{ -A multidimensional array with named dimensions. +A multidimensional array with named dimensions containing the +indicator in the element \code{data}. } \description{ -The Total Time of a variable exceeding (or not) a Threshold returns the total number of days -(if the data provided is daily, or the corresponding units to the data frequency provided) -that a variable is exceeding a threshold during a period. The threshold provided must be -in the same units than the variable units, i.e. to use a percentile as a threshold, -the function \code{Threshold} or \code{QThreshold} may be needed (see examples). -Providing maximum temperature daily data, the following agriculture indices for heat stress can be obtained by using this function: +The Total Time of a variable exceeding (or not) a Threshold returns the total +number of days (if the data provided is daily, or the corresponding units to +the data frequency provided) that a variable is exceeding a threshold during a +period. The threshold provided must be in the same units than the variable +units, i.e. to use a percentile as a threshold, the function \code{Threshold} +or \code{QThreshold} may be needed (see examples). Providing maximum +temperature daily data, the following agriculture indices for heat stress can +be obtained by using this function: \itemize{ - \item\code{SU35}{Total count of days when daily maximum temperatures exceed 35°C} - \item\code{SU36}{Total count of days when daily maximum temperatures exceed 36 between June 21st and September 21st} - \item\code{SU40}{Total count of days when daily maximum temperatures exceed 40 between June 21st and September 21st} - \item\code{Spr32}{Total count of days when daily maximum temperatures exceed 32 between April 21st and June 21st} + \item\code{SU35}{Total count of days when daily maximum temperatures exceed + 35°C} + \item\code{SU36}{Total count of days when daily maximum temperatures exceed + 36 between June 21st and September 21st} + \item\code{SU40}{Total count of days when daily maximum temperatures exceed + 40 between June 21st and September 21st} + \item\code{Spr32}{Total count of days when daily maximum temperatures exceed + 32 between April 21st and June 21st} } } \examples{ -exp <- CSTools::lonlat_data$exp$data[1, 5, 3, 3, 1, 1] +exp <- array(abs(rnorm(5 * 3 * 214 * 2)*280), + c(member = 5, sdate = 3, ftime = 214, lon = 2)) DOT <- TotalTimeExceedingThreshold(exp, threshold = 300, time_dim = 'ftime') } diff --git a/man/WindCapacityFactor.Rd b/man/WindCapacityFactor.Rd index 935a3e39198f7cd2b2ba45547eff275d27110bcf..557771e864a523db0a335f2e8e5bdfc8eb282e5d 100644 --- a/man/WindCapacityFactor.Rd +++ b/man/WindCapacityFactor.Rd @@ -15,27 +15,54 @@ WindCapacityFactor( ) } \arguments{ -\item{wind}{a multidimensional array, vector or scalar with instantaneous wind speeds expressed in m/s.} +\item{wind}{A multidimensional array, vector or scalar with instantaneous wind +speeds expressed in m/s.} -\item{IEC_class}{a string indicating the IEC wind class (see IEC 61400-1) of the turbine to be selected. Classes \code{'I'}, \code{'II'} and \code{'III'} are suitable for sites with an annual mean wind speed of 10, 8.5 and 7.5 m/s respectively. Classes \code{'I/II'} and \code{'II/III'} indicate intermediate turbines that fit both classes. More details of the five turbines and a plot of its power curves can be found in Lledó et al. (2019).} +\item{IEC_class}{A string indicating the IEC wind class (see IEC 61400-1) of +the turbine to be selected. Classes \code{'I'}, \code{'II'} and \code{'III'} +are suitable for sites with an annual mean wind speed of 10, 8.5 and 7.5 m/s +respectively. Classes \code{'I/II'} and \code{'II/III'} indicate +intermediate turbines that fit both classes. More details of the five +turbines and a plot of its power curves can be found in Lledó et al. (2019).} -\item{dates}{a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided.} +\item{dates}{A vector of dates or a multidimensional array of dates with named +dimensions matching the dimensions on parameter 'data'. By default it is +NULL, to select a period this parameter must be provided.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute the indicator. By default, it is set to 'ftime'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{ncores}{an integer indicating the number of cores to use in parallel computation for temporal subsetting.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation for temporal subsetting.} } \value{ -An array with the same dimensions as wind, containing the Wind Capacity Factor (unitless). +An array with the same dimensions as wind, containing the Wind + Capacity Factor (unitless). } \description{ -Wind capacity factor computes the wind power generated by a specific wind turbine model under specific wind speed conditions, and expresses it as a fraction of the rated capacity (i.e. maximum power) of the turbine. +Wind capacity factor computes the wind power generated by a +specific wind turbine model under specific wind speed conditions, and +expresses it as a fraction of the rated capacity (i.e. maximum power) of the +turbine. -It is computed by means of a tabular power curve that relates wind speed to power output. The tabular values are interpolated with a linear piecewise approximating function to obtain a smooth power curve. Five different power curves that span different IEC classes can be selected (see below). +It is computed by means of a tabular power curve that relates +wind speed to power output. The tabular values are interpolated with a linear +piecewise approximating function to obtain a smooth power curve. Five +different power curves that span different IEC classes can be selected (see +below). } \examples{ wind <- rweibull(n = 100, shape = 2, scale = 6) @@ -43,7 +70,8 @@ WCF <- WindCapacityFactor(wind, IEC_class = "III") } \references{ -Lledó, Ll., Torralba, V., Soret, A., Ramon, J., & Doblas-Reyes, F. J. (2019). Seasonal forecasts of wind power generation. Renewable Energy, 143, 91–100. https://doi.org/10.1016/j.renene.2019.04.135 +Lledó, Ll., Torralba, V., Soret, A., Ramon, J., & Doblas-Reyes, F. J. (2019). +Seasonal forecasts of wind power generation. Renewable Energy, 143, 91–100. https://doi.org/10.1016/j.renene.2019.04.135 International Standard IEC 61400-1 (third ed.) (2005) } diff --git a/man/WindPowerDensity.Rd b/man/WindPowerDensity.Rd index 5642edb311b9492e89a407878f37b1960d30df17..8e3c8e3d3d147ad0b3cb88c593ad6f390c51e189 100644 --- a/man/WindPowerDensity.Rd +++ b/man/WindPowerDensity.Rd @@ -15,27 +15,46 @@ WindPowerDensity( ) } \arguments{ -\item{wind}{a multidimensional array, vector or scalar with instantaneous wind speeds expressed in m/s.} +\item{wind}{A multidimensional array, vector or scalar with instantaneous wind +speeds expressed in m/s.} -\item{ro}{a scalar, or alternatively a multidimensional array with the same dimensions as wind, with the air density expressed in kg/m^3. By default it takes the value 1.225, the standard density of air at 15ºC and 1013.25 hPa.} +\item{ro}{A scalar, or alternatively a multidimensional array with the same +dimensions as wind, with the air density expressed in kg/m^3. By default it +takes the value 1.225, the standard density of air at 15ºC and 1013.25 hPa.} -\item{dates}{a vector of dates or a multidimensional array of dates with named dimensions matching the dimensions on parameter 'data'. By default it is NULL, to select a period this parameter must be provided.} +\item{dates}{A vector of dates or a multidimensional array of dates with named +dimensions matching the dimensions on parameter 'data'. By default it is +NULL, to select a period this parameter must be provided.} -\item{start}{an optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{start}{An optional parameter to defined the initial date of the period +to select from the data by providing a list of two elements: the initial +date of the period and the initial month of the period. By default it is set +to NULL and the indicator is computed using all the data provided in +\code{data}.} -\item{end}{an optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in \code{data}.} +\item{end}{An optional parameter to defined the final date of the period to +select from the data by providing a list of two elements: the final day of +the period and the final month of the period. By default it is set to NULL +and the indicator is computed using all the data provided in \code{data}.} -\item{time_dim}{a character string indicating the name of the function to compute the indicator. By default, it is set to 'ftime'. More than one dimension name matching the dimensions provided in the object \code{data$data} can be specified.} +\item{time_dim}{A character string indicating the name of the dimension to +compute the indicator. By default, it is set to 'ftime'. More than one +dimension name matching the dimensions provided in the object +\code{data$data} can be specified.} -\item{ncores}{an integer indicating the number of cores to use in parallel computation for temporal subsetting.} +\item{ncores}{An integer indicating the number of cores to use in parallel +computation for temporal subsetting.} } \value{ -An array with the same dimensions as wind, containing Wind Power Density expressed in W/m^2. +An array with the same dimensions as wind, containing Wind Power +Density expressed in W/m^2. } \description{ -Wind Power Density computes the wind power that is available for extraction per square meter of swept area. +Wind Power Density computes the wind power that is available for +extraction per square meter of swept area. -It is computed as 0.5*ro*wspd^3. As this function is non-linear, it will give inaccurate results if used with period means. +It is computed as 0.5*ro*wspd^3. As this function is non-linear, +it will give inaccurate results if used with period means. } \examples{ wind <- rweibull(n = 100, shape = 2, scale = 6) diff --git a/tests/testthat/test-MergeRefToExp.R b/tests/testthat/test-MergeRefToExp.R index a74df9036afb1fe82b70265012269ed9fbf1de64..b4503d86f34abf8c1348f4dafc7cd82dedc32d46 100644 --- a/tests/testthat/test-MergeRefToExp.R +++ b/tests/testthat/test-MergeRefToExp.R @@ -11,25 +11,81 @@ test_that("Sanity checks", { as.Date("01-12-1994", "%d-%m-%Y", tz = 'UTC'), "day") dim(ref_dates) <- c(ftime = 350, sdate = 2) ref <- array(1001:1700, c(ftime = 350, sdate = 2)) - data <- array(1:(2*154*2), c(ftime = 154, sdate = 2, member= 2)) + data <- array(1:(2 * 154 * 2), c(ftime = 154, sdate = 2, member= 2)) + +suppressWarnings( ref <- CSTools::s2dv_cube(data = ref, Dates = list(start = ref_dates, end = ref_dates)) +) +suppressWarnings( data <- CSTools::s2dv_cube(data = data, Dates = list(start = data_dates, end = data_dates)) - +) +suppressWarnings( expect_equal(CST_MergeRefToExp(data1 = ref, data2 = data, start1 = list(21, 6), end1 = list(30, 6), start2 = list(1, 7), end2 = list(21, 9))$Dates, SelectPeriodOnDates(ref_dates, start = list(21, 6), end = list(21,9))) +) output <- array(c(1172:1181, 1:83, 1537:1546, 155:237, 1172:1181, 309:391, 1537:1546, 463:545), c(ftime = 93, sdate = 2, member = 2)) +suppressWarnings( expect_equal(CST_MergeRefToExp(data1 = ref, data2 = data, start1 = list(21, 6), end1 = list(30, 6), start2 = list(1, 7), end2 = list(21, 9))$data, output) - }) +) + + # issue 13: One lead time + data_dates <- c(as.Date("01-06-1993", "%d-%m-%Y", tz = 'UTC'), + as.Date("01-07-1993", "%d-%m-%Y", tz = 'UTC'), + as.Date("01-06-1994", "%d-%m-%Y", tz = 'UTC'), + as.Date("01-07-1994","%d-%m-%Y", tz = 'UTC')) + + dim(data_dates) <- c(ftime = 2, sdate = 2) + ref_dates <- c(as.Date("01-05-1993", "%d-%m-%Y", tz = 'UTC'), + as.Date("01-05-1994", "%d-%m-%Y", tz = 'UTC')) + dim(ref_dates) <- c(ftime = 1, sdate = 2) + ref <- array(1:2, c(ftime = 1, sdate = 2)) + data <- array(1:(2 * 3 * 2), c(ftime = 2, sdate = 2, member = 3)) + +suppressWarnings( + ref <- CSTools::s2dv_cube(data = ref, Dates = list(start = ref_dates, + end = ref_dates)) +) +suppressWarnings( + data <- CSTools::s2dv_cube(data = data, Dates = list(start = data_dates, + end = data_dates)) +) + res_dates <- c(as.Date("01-05-1993", "%d-%m-%Y", tz = 'UTC'), + as.Date("01-06-1993", "%d-%m-%Y", tz = 'UTC'), + as.Date("01-07-1993", "%d-%m-%Y", tz = 'UTC'), + as.Date("01-05-1994", "%d-%m-%Y", tz = 'UTC'), + as.Date("01-06-1994", "%d-%m-%Y", tz = 'UTC'), + as.Date("01-07-1994","%d-%m-%Y", tz = 'UTC')) + dim(res_dates) <- c(ftime = 3, sdate = 2) + +suppressWarnings( + expect_equal(CST_MergeRefToExp(data1 = ref, data2 = data, start1 = list(1, 5), + end1 = list(31, 5), start2 = list(1, 6), + end2 = list(31, 7))$Dates, + res_dates) +) + + output <- abind::abind(t(matrix(rep(1:2, 3), ncol = 2, nrow = 3, byrow = T)), + data$data, along = 1) + names(dim(output)) <- c('ftime', 'sdate', 'member') + +suppressWarnings( + expect_equal(CST_MergeRefToExp(data1 = ref, data2 = data, start1 = list(1, 5), + end1 = list(31, 5), start2 = list(1, 6), + end2 = list(31, 7))$data, + output) +) + +}) test_that("Seasonal", { @@ -49,22 +105,32 @@ test_that("Seasonal", { dim(dates) <- dim.dates ref <- array(1:(215*25), c(ftime = 215, sdate = 25)) + +suppressWarnings( ref <- CSTools::s2dv_cube(data = ref, Dates = list(start = dates, end = dates)) +) data <- array(1:(215*25*3), c(ftime = 215, sdate = 25, member=3)) + +suppressWarnings( data <- CSTools::s2dv_cube(data = data, Dates = list(start = dates, end = dates)) +) +suppressWarnings( expect_equal(CST_MergeRefToExp(data1 = data, data2 = ref, start1 = list(21, 6), end1 = list(30, 6), start2 = list(1, 7), end2 = list(21, 9))$Dates, SelectPeriodOnDates(dates, start = list(21, 6), end = list(21,9))) +) +suppressWarnings( expect_equal(CST_MergeRefToExp(data1 = ref, data2 = data, start1 = list(21, 6), end1 = list(30, 6), start2 = list(1, 7), end2 = list(21, 9))$Dates, SelectPeriodOnDates(dates, start = list(21, 6), end = list(21,9))) +) }) diff --git a/tests/testthat/test-PeriodMean.R b/tests/testthat/test-PeriodMean.R index c9a0a37e40daf7e8dbda589d348f25367d03ac4b..75b6d576550eef3e1aed99a9e025490efbf28b84 100644 --- a/tests/testthat/test-PeriodMean.R +++ b/tests/testthat/test-PeriodMean.R @@ -2,15 +2,21 @@ context("Generic tests") test_that("Sanity Checks", { #source("csindicators/R/PeriodMean.R") expect_error(PeriodMean('x'), "Parameter 'data' must be numeric.") - expect_equal(PeriodMean(array(1, c(x = 1)), time_dim = 'x'), 1) + suppressWarnings( + expect_equal(PeriodMean(array(1, c(x = 1)), time_dim = 'x'), 1) + ) + expect_error(PeriodMean(data = NULL), "Parameter 'data' cannot be NULL.") expect_error(PeriodMean(1, dates = '2000-01-01', end = 3, start = 4), "Parameter 'start' and 'end' must be lists indicating the day and the month of the period start and end.") - - expect_equal(PeriodMean(array(1:10, c(time = 10))), 5.5) + suppressWarnings( + expect_equal(PeriodMean(array(1:10, c(time = 10))), 5.5) + ) data <- array(1:24, c(sdate = 2, time = 3, lon = 4)) - expect_equal(PeriodMean(data), - array(c(3,4,9,10,15,16,21,22), c(sdate = 2, lon = 4))) + suppressWarnings( + expect_equal(PeriodMean(data), + array(c(3,4,9,10,15,16,21,22), c(sdate = 2, lon = 4))) + ) }) test_that("seasonal", { diff --git a/vignettes/AgriculturalIndicators.Rmd b/vignettes/AgriculturalIndicators.Rmd index 3d9300d8d92e21b499dd407c00e3c2abe0cce0bf..50df881aefb029551ee3fdb74600c9beb4b426a6 100644 --- a/vignettes/AgriculturalIndicators.Rmd +++ b/vignettes/AgriculturalIndicators.Rmd @@ -66,9 +66,9 @@ With `grid` set to **r1440x721**, the SEAS5 forecast would be interpolated to th ``` -S5path_prlr <- list(path = '/esarchive/exp/ecmwf/system5c3s/original_files/chou/daily_mean/$VAR_NAME$_s0-24h/$VAR_NAME$_$YEAR$$MONTH$01.nc') +S5path_prlr <- list(path = '/esarchive/exp/ecmwf/system5c3s/$STORE_FREQ$_mean/$VAR_NAME$_s0-24h/$VAR_NAME$_$START_DATE$.nc') -path_ERA5prlr_CDS <- list(path = '/esarchive/recon/ecmwf/era5/daily_mean/$VAR_NAME$_f1h-r1440x721cds/$VAR_NAME$_$YEAR$$MONTH$.nc') +path_ERA5prlr_CDS <- list(path = '/esarchive/recon/ecmwf/era5/$STORE_FREQ$_mean/$VAR_NAME$_f1h-r1440x721cds/$VAR_NAME$_$YEAR$$MONTH$.nc') sdates <- paste0(2013:2016, '04', '01') @@ -182,8 +182,8 @@ For the function `PeriodMean`, we use Growing Season Temperature (**GST**) as an Firstly, we prepare a sample data of daily mean temperature of SEAS5 and ERA5 data sets with the same starting dates, spatial domain, interpolation grid and method by running ``` -S5path <- list(path = '/esarchive/exp/ecmwf/system5c3s/daily_mean/$VAR_NAME$_f6h/$VAR_NAME$_$YEAR$$MONTH$01.nc') -ERA5path <- list(path = '/esarchive/recon/ecmwf/era5/daily_mean/$VAR_NAME$_f1h-r1440x721cds/$VAR_NAME$_$YEAR$$MONTH$.nc') +S5path <- list(path = '/esarchive/exp/ecmwf/system5c3s/$STORE_FREQ$_mean/$VAR_NAME$_f6h/$VAR_NAME$_$YEAR$$MONTH$01.nc') +ERA5path <- list(path = '/esarchive/recon/ecmwf/era5/$STORE_FREQ$_mean/$VAR_NAME$_f1h-r1440x721cds/$VAR_NAME$_$YEAR$$MONTH$.nc') c(tas_exp, tas_obs) %<-% CST_Load(var = 'tas', exp = list(S5path), obs = list(ERA5path), sdates = sdates, lonmax = 353, lonmin = 352.25, @@ -206,8 +206,8 @@ dim(tas_exp$data) # 1 3 4 214 4 4 summary(tas_obs$data - 273.15) -# Min. 1st Qu. Median Mean 3rd Qu. Max. -# 3.63 14.38 17.89 17.65 21.24 30.21 +# Min. 1st Qu. Median Mean 3rd Qu. Max. +# 3.63 13.97 17.25 17.29 20.75 30.21 summary(tas_exp$data - 273.15) # Min. 1st Qu. Median Mean 3rd Qu. Max. @@ -235,12 +235,12 @@ The summaries and dimensions of the output are as follows: ``` summary(GST_exp$data) -# Min. 1st Qu. Median Mean 3rd Qu. Max. +# Min. 1st Qu. Median Mean 3rd Qu. Max. # 14.23 15.78 16.50 16.50 17.17 18.70 summary(GST_obs$data) -# Min. 1st Qu. Median Mean 3rd Qu. Max. -# 15.34 16.85 17.72 17.65 18.41 19.60 +# Min. 1st Qu. Median Mean 3rd Qu. Max. +# 15.34 16.77 17.22 17.29 18.00 18.75 dim(GST_exp$data) #dataset member sdate lat lon @@ -292,8 +292,8 @@ Here, we take SU35 as example, therefore the daily temperature maximum of the en Load SEAS5 and ERA5 daily temperature maximum by running ``` -S5path <- list(path = '/esarchive/exp/ecmwf/system5c3s/daily/$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$01.nc') -ERA5path <- list(path = '/esarchive/recon/ecmwf/era5/daily/$VAR_NAME$-r1440x721cds/$VAR_NAME$_$YEAR$$MONTH$.nc') +S5path <- list(path = '/esarchive/exp/ecmwf/system5c3s/$STORE_FREQ$/$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$01.nc') +ERA5path <- list(path = '/esarchive/recon/ecmwf/era5/$STORE_FREQ$/$VAR_NAME$-r1440x721cds/$VAR_NAME$_$YEAR$$MONTH$.nc') c(tasmax_exp, tasmax_obs) %<-% CST_Load(var = 'tasmax', exp = list(S5path), obs = list(ERA5path), sdates = sdates, @@ -482,7 +482,7 @@ summary(GDD_exp$data) summary(GDD_obs$data) # Min. 1st Qu. Median Mean 3rd Qu. Max. -# 1195 1504 1687 1660 1804 2055 +# 1195 1483 1569 1583 1730 1874 ``` To compute the correlation coefficient for the period from 2013-2016, run the following lines @@ -534,8 +534,8 @@ dim(tx_p$data) # 1 214 4 4 summary(tx_p$data) -# Min. 1st Qu. Median Mean 3rd Qu. Max. -# 287.0 295.2 299.2 299.4 303.9 309.9 +# Min. 1st Qu. Median Mean 3rd Qu. Max. +# 13.83 22.08 26.08 26.22 30.72 36.72 ``` With the prepared threshold (90th percentile), the WSDI can be computed by running @@ -554,12 +554,12 @@ obs <- Reorder(drop(WSDI_obs$data), c(3, 2, 1)) # summaries of WSDI summary(fcst) -# Min. 1st Qu. Median Mean 3rd Qu. Max. -# 0.00 13.00 28.00 30.65 42.25 82.00 - +# Min. 1st Qu. Median Mean 3rd Qu. Max. +# 0.00 13.00 28.00 31.22 46.00 82.00 + summary(obs) -# Min. 1st Qu. Median Mean 3rd Qu. Max. -# 9.00 19.00 22.50 22.91 25.25 33.00 +# Min. 1st Qu. Median Mean 3rd Qu. Max. +# 9.00 19.00 22.50 23.16 26.00 33.00 # compute FRPSS f <- veriApply('FairRpss', fcst = fcst, obs = obs, ensdim = 4, tdim = 3, prob = 1:2/3)$skillscore diff --git a/vignettes/EnergyIndicators.Rmd b/vignettes/EnergyIndicators.Rmd index 222ba3829e2d4df3c2ade0be674b7414fab7bd4e..caf474e68d2ba86a04b41f87d9efa300d216cf6a 100644 --- a/vignettes/EnergyIndicators.Rmd +++ b/vignettes/EnergyIndicators.Rmd @@ -30,7 +30,7 @@ Although wind turbines cannot extract all of the kinetic energy in the wind, and As an example, we simulate a time series of 1000 wind speed values from a Weibull distribution with scale factor of 6 and a shape factor of 2, which represent a sample of wind speed values obtained at a single location. The Weibull distribution is often assumed to fit observed wind speed values to a probability distribution function. Then, each instantaneous wind speed value is converted to its equivalent WPD. The `mean` and `sd` of the WPD can be employed to summarize the wind resource in that location. Otherwise, we can plot the histograms to see the full distribution of values: -```{r} +```{r, fig.width=7} library(CSIndicators) set.seed(1) oldpar <- par(no.readonly = TRUE) @@ -42,7 +42,6 @@ par(mfrow=c(1, 2)) hist(wind, breaks = seq(0, 20)) hist(WPD, breaks = seq(0, 4000, 200)) ``` - As you can see the histogram of the WPD is highly skewed, even if the wind speed was only a little skewed! @@ -62,7 +61,7 @@ Notice that power curves are intended to be used with 10-minutal steady wind spe Following on the previous example, we will compute now the CF that would be obtained from our sample of 1000 wind speed values when using a turbine of class IEC I, and compare it to the CF values for a class III: -```{r} +```{r, fig.width=7} WCFI <- WindCapacityFactor(wind, IEC_class = "I") WCFIII <- WindCapacityFactor(wind, IEC_class = "III") par(mfrow=c(1, 3)) @@ -72,7 +71,6 @@ hist(WCFIII, breaks = seq(0, 1, 0.05), ylim = c(0, 500)) par(oldpar) ``` - From the CF histograms we can see that, for this particular wind speed distribution, the IEC I turbine (designed for high winds) producess less energy than the IEC III turbine, which is more suitable for this range of wind speed values. diff --git a/vignettes/figures/GDD_SEAS5_Corr_Y13-16-1.png b/vignettes/figures/GDD_SEAS5_Corr_Y13-16-1.png index 43e291cfa9295e5011912f10b02326cdb4762795..5d05be945f1dc68da843d2b67436a05a23315cee 100644 Binary files a/vignettes/figures/GDD_SEAS5_Corr_Y13-16-1.png and b/vignettes/figures/GDD_SEAS5_Corr_Y13-16-1.png differ diff --git a/vignettes/figures/GST_ERA5_Climatology-1.png b/vignettes/figures/GST_ERA5_Climatology-1.png index 90128537ef623ee0e360f271168a38248999a2c1..e5c5890f6c04015a960e0ef5236046e2da096967 100644 Binary files a/vignettes/figures/GST_ERA5_Climatology-1.png and b/vignettes/figures/GST_ERA5_Climatology-1.png differ