diff --git a/DESCRIPTION b/DESCRIPTION index 28a2634ba0bf876f2f9b062e01d84238e7e08d81..6dae74dc29205f9729ff88cf68b6711af046cccb 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -28,4 +28,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/R/AbsToProbs.R b/R/AbsToProbs.R index af7b616228489146a171cfc56615102effddea4a..ce5f01ae9f5a3eb3ce0bf20fb18c891656f9600e 100644 --- a/R/AbsToProbs.R +++ b/R/AbsToProbs.R @@ -1,32 +1,50 @@ #'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_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', @@ -63,34 +81,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_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..62a4bc44a08bab8e7030cdb74f7115dfb79fce76 100644 --- a/R/AccumulationExceedingThreshold.R +++ b/R/AccumulationExceedingThreshold.R @@ -1,35 +1,57 @@ #'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 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. #' #'@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] #'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.") @@ -53,9 +75,9 @@ CST_AccumulationExceedingThreshold <- function(data, threshold, op = '>', 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 +88,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 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. #' -#'@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 +146,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 +161,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 +187,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 +226,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 2dd5af2cc59d1b8bee2b67e93bdcc4c607724a11..837d3045817b71226c9d0ade96e921bf274812bf 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'), @@ -34,6 +56,9 @@ #'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', @@ -73,19 +98,19 @@ CST_MergeRefToExp <- function(data1, data2, start1, end1, start2, end2, } } 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 + c, output_dims = time_dim, ncores = ncores)$output1 if (class(data1$Dates[[1]]) == 'Date') { data1$Dates <- as.Date(res, origin = '1970-01-01') } else { @@ -96,26 +121,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 +171,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', @@ -155,8 +200,7 @@ MergeRefToExp <- function(data1, dates1, start1, end1, data2, dates2, start2, en 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))) { @@ -175,7 +219,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]) + name = names(dim(data2))[i]) } } } @@ -185,14 +229,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]) + 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..92ec947dcca7966fad696b73110a63a277efb908 100644 --- a/R/PeriodAccumulation.R +++ b/R/PeriodAccumulation.R @@ -1,21 +1,37 @@ #'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 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. #' -#'@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 @@ -23,17 +39,19 @@ #'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, @@ -62,30 +80,47 @@ 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 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. #' -#'@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 @@ -95,12 +130,14 @@ CST_PeriodAccumulation <- function(data, start = NULL, end = NULL, #'# 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..c75cee3f09826fc8c497cdbe9685792c818483b8 100644 --- a/R/PeriodMean.R +++ b/R/PeriodMean.R @@ -1,27 +1,44 @@ #'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 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. #' -#'@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] #'SA <- CST_PeriodMean(exp) #' +#'@import multiApply #'@export CST_PeriodMean <- function(data, start = NULL, end = NULL, time_dim = 'ftime', na.rm = FALSE, @@ -59,26 +76,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 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. #' -#'@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 #'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..6b4359d13fbfdffe4b9ee7997fcbac82db90413f 100644 --- a/R/QThreshold.R +++ b/R/QThreshold.R @@ -1,29 +1,55 @@ #'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 @@ -32,12 +58,15 @@ #'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')) +#' 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)) +#' +#'@import multiApply +#'@importFrom ClimProjDiags Subset #'@export CST_QThreshold <- function(data, threshold, start = NULL, end = NULL, time_dim = 'ftime', memb_dim = 'member', sdate_dim = 'sdate', @@ -77,36 +106,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 +213,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 +263,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 +271,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 85b7ff33d7d3a35e0a95df96f1fcab636df1faca..f15c60e1095228ccb98fdcd4c34195f0006eb067 100644 --- a/R/SelectPeriodOnData.R +++ b/R/SelectPeriodOnData.R @@ -2,27 +2,37 @@ #' #' 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$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)) #'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')) #'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')) { @@ -50,8 +60,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 +71,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) { 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..755c2e603ed0136266502dfe7f7bdcd2a529299f 100644 --- a/R/Threshold.R +++ b/R/Threshold.R @@ -1,21 +1,40 @@ #'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 @@ -24,17 +43,19 @@ #'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')) +#' 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_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.") } @@ -54,36 +75,55 @@ CST_Threshold <- function(data, threshold, start = NULL, end = NULL, } } 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..97981ee0dfe1827906e3faca075b616ff3881613 100644 --- a/R/TotalSpellTimeExceedingThreshold.R +++ b/R/TotalSpellTimeExceedingThreshold.R @@ -1,34 +1,61 @@ #'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 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. #' -#'@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)) +#' c(member = 5, sdate = 3, ftime = 20, lon = 2)) #'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.") @@ -65,31 +92,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 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. #' -#'@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 +162,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 +178,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 +205,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..ee0d8ac9a7f7c069153448fb4cc393b07642a2d7 100644 --- a/R/TotalTimeExceedingThreshold.R +++ b/R/TotalTimeExceedingThreshold.R @@ -1,34 +1,60 @@ #'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 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. #' -#'@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] #'DOT <- CST_TotalTimeExceedingThreshold(exp, threshold = 280) +#' +#'@import multiApply #'@export CST_TotalTimeExceedingThreshold <- function(data, threshold, op = '>', start = NULL, end = NULL, @@ -70,36 +96,61 @@ 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 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. #' -#'@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] #'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..61565b03556e91619bcc56f9979e7f0928bf893d 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 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 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 @@ -54,35 +78,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 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 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..99d5d80e8045bdca543f72e0b8244b89c7ab0dbf 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 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 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 @@ -61,18 +77,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 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 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/man/AbsToProbs.Rd b/man/AbsToProbs.Rd index c4507a28e29d0cbb31b17abaebee0c4ffb279a92..89b1f8346120fbf5c9a6d954b8accc724fb01ba0 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_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..f7e09825f02f76ac6d6c125330f865a34bc9132a 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 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{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..dcdcef9ebd8c3428f56a437c81e1e8c1eeb28ba1 100644 --- a/man/CST_AbsToProbs.Rd +++ b/man/CST_AbsToProbs.Rd @@ -15,36 +15,55 @@ 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_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..9785f9705a2f6b06a71d6d0633294ba3ab67329b 100644 --- a/man/CST_AccumulationExceedingThreshold.Rd +++ b/man/CST_AccumulationExceedingThreshold.Rd @@ -17,37 +17,59 @@ 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 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{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] DOT <- CST_AccumulationExceedingThreshold(exp, threshold = 280) + } diff --git a/man/CST_MergeRefToExp.Rd b/man/CST_MergeRefToExp.Rd index 61c184048246628ed9c5e625f4d544771aec016d..102b0620bb2deb804be43ad56ca2a14aa43292c6 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'), @@ -59,4 +84,5 @@ data <- CSTools::s2dv_cube(data = data, Dates = list(start = data_dates, 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..5a2c3ce8db1e95b011693e95509d25e7609cf51f 100644 --- a/man/CST_PeriodAccumulation.Rd +++ b/man/CST_PeriodAccumulation.Rd @@ -14,27 +14,45 @@ 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 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{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 @@ -42,15 +60,16 @@ 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..574e476b82640ce89f2e0e7c09fa88b8843c9733 100644 --- a/man/CST_PeriodMean.Rd +++ b/man/CST_PeriodMean.Rd @@ -14,27 +14,45 @@ 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 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{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 diff --git a/man/CST_QThreshold.Rd b/man/CST_QThreshold.Rd index 744724aa88ec883524abef4a734f122317c15f76..a01c5d2293ef3d7368a9fc26938a7a74ab87e70d 100644 --- a/man/CST_QThreshold.Rd +++ b/man/CST_QThreshold.Rd @@ -16,36 +16,66 @@ 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 @@ -54,10 +84,11 @@ 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')) + 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)) + } diff --git a/man/CST_SelectPeriodOnData.Rd b/man/CST_SelectPeriodOnData.Rd index 2bac4182945cc2a22df20757ab1114193d932672..210fcaaf10c1feff92eae5b084b15606621cb4eb 100644 --- a/man/CST_SelectPeriodOnData.Rd +++ b/man/CST_SelectPeriodOnData.Rd @@ -7,18 +7,28 @@ 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. @@ -26,12 +36,13 @@ Auxiliary function to subset data for a specific period. \examples{ exp <- CSTools::lonlat_prec exp$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)) 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')) 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..906d1b18d2e985d7e8b4b28ca27840f84ffcfc0a 100644 --- a/man/CST_Threshold.Rd +++ b/man/CST_Threshold.Rd @@ -17,30 +17,51 @@ 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 @@ -49,10 +70,11 @@ exp_probs <- CST_Threshold(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')) + 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_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..d395ae6393a7008f0ee6d0148cfba4295c311a84 100644 --- a/man/CST_TotalSpellTimeExceedingThreshold.Rd +++ b/man/CST_TotalSpellTimeExceedingThreshold.Rd @@ -16,37 +16,64 @@ 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 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{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)) + c(member = 5, sdate = 3, ftime = 20, lon = 2)) 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..3c5c11f954760cfb98777ea286e348b7831d55e0 100644 --- a/man/CST_TotalTimeExceedingThreshold.Rd +++ b/man/CST_TotalTimeExceedingThreshold.Rd @@ -16,41 +16,67 @@ 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 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{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] DOT <- CST_TotalTimeExceedingThreshold(exp, threshold = 280) + } diff --git a/man/CST_WindCapacityFactor.Rd b/man/CST_WindCapacityFactor.Rd index 9e0a46cdafa9c6c69ae316248e4b7b60f17fd6cc..28f437fb4cebf6e8f6f58683305884dd7b5d3c17 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 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{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..9e534571b9f674e66869fb3965b9006f7f87c8f9 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 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{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..1f23e66703c5f56daed69068f1150dad22bc89c2 100644 --- a/man/PeriodAccumulation.Rd +++ b/man/PeriodAccumulation.Rd @@ -15,29 +15,48 @@ 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 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{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 @@ -47,10 +66,11 @@ data <- array(rnorm(5 * 3 * 214 * 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..19fb9bf71b447876261dd26fd4aeb5983c7af6e0 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 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{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 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..2bcebfaa8e17ec34015616067a10485b3d65bcfa 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 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{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..119d3922eca1e8d5e46cc91295aeae726d0fc0a7 100644 --- a/man/TotalTimeExceedingThreshold.Rd +++ b/man/TotalTimeExceedingThreshold.Rd @@ -17,39 +17,64 @@ 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 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{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{ diff --git a/man/WindCapacityFactor.Rd b/man/WindCapacityFactor.Rd index 935a3e39198f7cd2b2ba45547eff275d27110bcf..4779ff09367fd7f3963caae16c84a5f2c7597930 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 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{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..af919a617c6caa289fa1b207b6714394ff8af338 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 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{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)