From f35a19123d8ed68f8bc32ca67da21e0befb284c8 Mon Sep 17 00:00:00 2001 From: Eva Rifa Date: Thu, 22 Sep 2022 18:28:48 +0200 Subject: [PATCH 1/3] Correct documentation and formatting --- DESCRIPTION | 2 +- R/QThreshold.R | 155 +++++++++++++++++++++++++++++------------- R/Threshold.R | 109 ++++++++++++++++++++--------- man/CST_QThreshold.Rd | 67 +++++++++++++----- man/CST_Threshold.Rd | 46 +++++++++---- man/QThreshold.Rd | 68 ++++++++++++------ man/Threshold.Rd | 49 +++++++++---- 7 files changed, 352 insertions(+), 144 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 28a2634..6dae74d 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/QThreshold.R b/R/QThreshold.R index 067c495..f0bb736 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 @@ -38,6 +64,9 @@ #' 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/Threshold.R b/R/Threshold.R index c09ebe0..8112cf6 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 @@ -30,6 +49,8 @@ #' 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', @@ -66,24 +87,43 @@ CST_Threshold <- function(data, threshold, start = NULL, end = NULL, } #'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/man/CST_QThreshold.Rd b/man/CST_QThreshold.Rd index 744724a..2843999 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 @@ -60,4 +90,5 @@ exp$Dates[[1]] <- c(seq(as.Date("01-05-2000", 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')) exp_probs <- CST_QThreshold(exp, threshold, start = list(21, 4), end = list(21, 6)) + } diff --git a/man/CST_Threshold.Rd b/man/CST_Threshold.Rd index bff93fa..e344ca1 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 @@ -55,4 +76,5 @@ exp$Dates[[1]] <- c(seq(as.Date("01-05-2000", 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')) exp_probs <- CST_Threshold(exp, threshold, start = list(21, 4), end = list(21, 6)) + } diff --git a/man/QThreshold.Rd b/man/QThreshold.Rd index ff4900e..2af6e5f 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/Threshold.Rd b/man/Threshold.Rd index c2f3872..2999439 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) + } -- GitLab From 7c2fa5359bbcfd910f42642a625198e5360113ab Mon Sep 17 00:00:00 2001 From: Eva Rifa Date: Fri, 23 Sep 2022 12:42:40 +0200 Subject: [PATCH 2/3] Correct documentation and formatting of all functions --- R/AbsToProbs.R | 88 +++++++++---- R/AccumulationExceedingThreshold.R | 136 +++++++++++++------- R/MergeRefToExp.R | 134 ++++++++++++------- R/PeriodAccumulation.R | 95 +++++++++----- R/PeriodMean.R | 86 +++++++++---- R/SelectPeriodOnData.R | 76 +++++++---- R/SelectPeriodOnDates.R | 28 ++-- R/TotalSpellTimeExceedingThreshold.R | 135 +++++++++++++------ R/TotalTimeExceedingThreshold.R | 135 +++++++++++++------ R/WindCapacityFactor.R | 110 +++++++++++----- R/WindPowerDensity.R | 81 ++++++++---- R/zzz.R | 6 +- man/AbsToProbs.Rd | 41 ++++-- man/AccumulationExceedingThreshold.Rd | 55 +++++--- man/CST_AbsToProbs.Rd | 37 ++++-- man/CST_AccumulationExceedingThreshold.Rd | 50 +++++-- man/CST_MergeRefToExp.Rd | 48 +++++-- man/CST_PeriodAccumulation.Rd | 41 ++++-- man/CST_PeriodMean.Rd | 38 ++++-- man/CST_SelectPeriodOnData.Rd | 35 +++-- man/CST_TotalSpellTimeExceedingThreshold.Rd | 55 ++++++-- man/CST_TotalTimeExceedingThreshold.Rd | 64 ++++++--- man/CST_WindCapacityFactor.Rd | 52 ++++++-- man/CST_WindPowerDensity.Rd | 42 ++++-- man/MergeRefToExp.Rd | 45 +++++-- man/PeriodAccumulation.Rd | 44 +++++-- man/PeriodMean.Rd | 42 ++++-- man/SelectPeriodOnData.Rd | 31 +++-- man/SelectPeriodOnDates.Rd | 26 ++-- man/TotalSpellTimeExceedingThreshold.Rd | 59 ++++++--- man/TotalTimeExceedingThreshold.Rd | 65 +++++++--- man/WindCapacityFactor.Rd | 50 +++++-- man/WindPowerDensity.Rd | 39 ++++-- 33 files changed, 1462 insertions(+), 607 deletions(-) diff --git a/R/AbsToProbs.R b/R/AbsToProbs.R index af7b616..155d745 100644 --- a/R/AbsToProbs.R +++ b/R/AbsToProbs.R @@ -1,19 +1,34 @@ #'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 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 stats ecdf +#'@return An 's2dv_cube' object containing the probabilites in the element \code{data}. #' #'@examples #'exp <- CSTools::lonlat_prec @@ -27,6 +42,9 @@ #' 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,21 +81,38 @@ 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 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. -#' -#'@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 @@ -91,6 +126,9 @@ CST_AbsToProbs <- function(data, start = NULL, end = NULL, #' 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 e953d32..62a4bc4 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 2dd5af2..3332ffb 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 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}. #' #'@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 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 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 f9cdb18..2782af3 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 @@ -34,6 +50,8 @@ #'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 @@ -101,6 +136,8 @@ CST_PeriodAccumulation <- function(data, start = NULL, end = NULL, #' 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 fa3af03..c75cee3 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/SelectPeriodOnData.R b/R/SelectPeriodOnData.R index 85b7ff3..f15c60e 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 c8444c0..a9c8d9c 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/TotalSpellTimeExceedingThreshold.R b/R/TotalSpellTimeExceedingThreshold.R index 0ecbe9e..97981ee 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 3792caf..ee0d8ac 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 4b9bffb..61565b0 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 1ecdc30..99d5d80 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 35cd5a6..52fa2cd 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 c4507a2..c3e7c50 100644 --- a/man/AbsToProbs.Rd +++ b/man/AbsToProbs.Rd @@ -16,27 +16,47 @@ 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 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 +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 @@ -50,4 +70,5 @@ Dates <- c(seq(as.Date("01-05-2000", format = "\%d-\%m-\%Y"), 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 0dd414f..f7e0982 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 ec1bd8f..8ac3c37 100644 --- a/man/CST_AbsToProbs.Rd +++ b/man/CST_AbsToProbs.Rd @@ -15,25 +15,43 @@ 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 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 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 @@ -47,4 +65,5 @@ exp$Dates[[1]] <- c(seq(as.Date("01-05-2000", 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')) 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 4fbcebc..9785f97 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 61c1840..961eab9 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 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{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 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{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 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{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 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{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 0337a13..aea9560 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 @@ -53,4 +71,5 @@ 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 1beefc5..574e476 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_SelectPeriodOnData.Rd b/man/CST_SelectPeriodOnData.Rd index 2bac418..210fcaa 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_TotalSpellTimeExceedingThreshold.Rd b/man/CST_TotalSpellTimeExceedingThreshold.Rd index 8e65e58..d395ae6 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 e1d3c7d..3c5c11f 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 9e0a46c..28f437f 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 8033bfe..9e53457 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 9826df7..32e8627 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 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{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 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{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 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{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 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{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 fbc225a..3fa9bb8 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 @@ -53,4 +72,5 @@ Dates <- c(seq(as.Date("01-05-2000", 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 6062daa..19fb9bf 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/SelectPeriodOnData.Rd b/man/SelectPeriodOnData.Rd index dabb190..118cb98 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 2cd553a..cce8e55 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/TotalSpellTimeExceedingThreshold.Rd b/man/TotalSpellTimeExceedingThreshold.Rd index bbbfe35..2bcebfa 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 855ef86..119d392 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 935a3e3..4779ff0 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 5642edb..af919a6 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) -- GitLab From 74b261f3e044ee24df28aebe76a6b959fd34f9b3 Mon Sep 17 00:00:00 2001 From: Eva Rifa Date: Fri, 23 Sep 2022 12:53:59 +0200 Subject: [PATCH 3/3] Correct formatting --- R/AbsToProbs.R | 32 ++++++++++++++++---------------- R/MergeRefToExp.R | 16 ++++++++-------- R/PeriodAccumulation.R | 14 +++++++------- R/QThreshold.R | 10 +++++----- R/Threshold.R | 32 ++++++++++++++++---------------- man/AbsToProbs.Rd | 16 ++++++++-------- man/CST_AbsToProbs.Rd | 16 ++++++++-------- man/CST_MergeRefToExp.Rd | 8 ++++---- man/CST_PeriodAccumulation.Rd | 10 +++++----- man/CST_QThreshold.Rd | 10 +++++----- man/CST_Threshold.Rd | 10 +++++----- man/MergeRefToExp.Rd | 8 ++++---- man/PeriodAccumulation.Rd | 4 ++-- man/Threshold.Rd | 6 +++--- 14 files changed, 96 insertions(+), 96 deletions(-) diff --git a/R/AbsToProbs.R b/R/AbsToProbs.R index 155d745..ce5f01a 100644 --- a/R/AbsToProbs.R +++ b/R/AbsToProbs.R @@ -7,12 +7,12 @@ #' #'@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 +#'@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 defined the final date of the period to +#'@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}. @@ -34,13 +34,13 @@ #'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 @@ -90,12 +90,12 @@ CST_AbsToProbs <- function(data, start = NULL, end = NULL, #'@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 +#'@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 defined the final date of the period to +#'@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}. @@ -118,13 +118,13 @@ CST_AbsToProbs <- function(data, start = NULL, end = NULL, #'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 diff --git a/R/MergeRefToExp.R b/R/MergeRefToExp.R index 3332ffb..837d304 100644 --- a/R/MergeRefToExp.R +++ b/R/MergeRefToExp.R @@ -15,16 +15,16 @@ #' 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 +#'@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 defined the final date of the period to select from +#'@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 defined the initial date of the period to select from +#'@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 defined the final date of the period to select from +#'@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 @@ -134,16 +134,16 @@ CST_MergeRefToExp <- function(data1, data2, start1, end1, start2, end2, #'@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 +#'@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 defined the final date of the period to select from +#'@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 defined the initial date of the period to select from +#'@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 defined the final date of the period to select from +#'@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 diff --git a/R/PeriodAccumulation.R b/R/PeriodAccumulation.R index 2782af3..92ec947 100644 --- a/R/PeriodAccumulation.R +++ b/R/PeriodAccumulation.R @@ -39,11 +39,11 @@ #'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) @@ -130,9 +130,9 @@ 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)) diff --git a/R/QThreshold.R b/R/QThreshold.R index f0bb736..6b4359d 100644 --- a/R/QThreshold.R +++ b/R/QThreshold.R @@ -58,11 +58,11 @@ #'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 diff --git a/R/Threshold.R b/R/Threshold.R index 8112cf6..755c2e6 100644 --- a/R/Threshold.R +++ b/R/Threshold.R @@ -43,19 +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.") } @@ -75,22 +75,22 @@ 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. +#'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 diff --git a/man/AbsToProbs.Rd b/man/AbsToProbs.Rd index c3e7c50..89b1f83 100644 --- a/man/AbsToProbs.Rd +++ b/man/AbsToProbs.Rd @@ -22,13 +22,13 @@ AbsToProbs( 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 +\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 +\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}.} @@ -62,13 +62,13 @@ Distribution Function excluding the corresponding initialization. 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/CST_AbsToProbs.Rd b/man/CST_AbsToProbs.Rd index 8ac3c37..dcdcef9 100644 --- a/man/CST_AbsToProbs.Rd +++ b/man/CST_AbsToProbs.Rd @@ -18,13 +18,13 @@ CST_AbsToProbs( \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 +\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 +\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}.} @@ -57,13 +57,13 @@ Distribution Function excluding the corresponding initialization. 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_MergeRefToExp.Rd b/man/CST_MergeRefToExp.Rd index 961eab9..102b062 100644 --- a/man/CST_MergeRefToExp.Rd +++ b/man/CST_MergeRefToExp.Rd @@ -23,19 +23,19 @@ 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 +\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 +\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 +\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 +\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.} diff --git a/man/CST_PeriodAccumulation.Rd b/man/CST_PeriodAccumulation.Rd index aea9560..5a2c3ce 100644 --- a/man/CST_PeriodAccumulation.Rd +++ b/man/CST_PeriodAccumulation.Rd @@ -60,11 +60,11 @@ 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) diff --git a/man/CST_QThreshold.Rd b/man/CST_QThreshold.Rd index 2843999..a01c5d2 100644 --- a/man/CST_QThreshold.Rd +++ b/man/CST_QThreshold.Rd @@ -84,11 +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_Threshold.Rd b/man/CST_Threshold.Rd index e344ca1..906d1b1 100644 --- a/man/CST_Threshold.Rd +++ b/man/CST_Threshold.Rd @@ -70,11 +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/MergeRefToExp.Rd b/man/MergeRefToExp.Rd index 32e8627..f5b4958 100644 --- a/man/MergeRefToExp.Rd +++ b/man/MergeRefToExp.Rd @@ -24,11 +24,11 @@ MergeRefToExp( \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 +\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 +\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.} @@ -37,11 +37,11 @@ the final month of the period.} \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 +\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 +\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.} diff --git a/man/PeriodAccumulation.Rd b/man/PeriodAccumulation.Rd index 3fa9bb8..1f23e66 100644 --- a/man/PeriodAccumulation.Rd +++ b/man/PeriodAccumulation.Rd @@ -66,9 +66,9 @@ 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/Threshold.Rd b/man/Threshold.Rd index 2999439..db59817 100644 --- a/man/Threshold.Rd +++ b/man/Threshold.Rd @@ -62,9 +62,9 @@ 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 +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{ -- GitLab