From 8dd06d5ba8b342a095643ff84fce73d34505c2aa Mon Sep 17 00:00:00 2001 From: nperez Date: Mon, 22 Feb 2021 09:11:37 +0100 Subject: [PATCH 1/5] ProbBins first version --- R/ProbBins.R | 168 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 R/ProbBins.R diff --git a/R/ProbBins.R b/R/ProbBins.R new file mode 100644 index 0000000..b0bc279 --- /dev/null +++ b/R/ProbBins.R @@ -0,0 +1,168 @@ +#'Computes Probabilistic Information of a Forecast Relative to a Threshold or a Quantile +#' +#'Compute probabilistic bins of a set of forecast years ('fcyr') relative to +#'the forecast climatology over the whole period of anomalies, optionally excluding +#'the selected forecast years ('fcyr') or the forecast year for which the +#'probabilistic bins are being computed (see 'compPeriod'). +#' +#'@param ano Array of anomalies from Ano().\cr +#' Must be of dimension (nexp/nobs, nmemb, nsdates, nleadtime, nlat, nlon) +#'@param fcyr Indices of the forecast years of the anomalies which to compute +#' the probabilistic bins for, or 'all' to compute the bins for all the +#' years.\cr +#' E.g., c(1:5), c(1, 4), 4 or 'all'. +#'@param thr Values used as thresholds to bin the anomalies. +#'@param quantile If quantile is TRUE (default), the threshold ('thr') +#' are quantiles.\cr +#' If quantile is FALSE the thresholds ('thr') introduced are the absolute +#' thresholds of the bins. +#'@param posdates Position of the dimension in \code{ano} that corresponds to +#' the start dates (default = 3). +#'@param posdim Position of the dimension in \code{ano} which will be combined +#' with 'posdates' to compute the quantiles (default = 2, ensemble members). +#'@param compPeriod Three options: +#' "Full period"/"Without fcyr"/"Cross-validation" (The probabilities are +#' computed with the terciles based on ano/ano with all 'fcyr's +#' removed/cross-validation). The default is "Full period". +#' +#'@return Array with probabilistic information and dimensions:\cr +#' c(length('thr') + 1, length(fcyr), nmemb/nparam, nmod/nexp/nobs, +#' nltime, nlat, nlon)\cr +#' The values along the first dimension take values 0 or 1 depending on which +#' of the 'thr'+1 cathegories the forecast/observation at the corresponding +#' grid point, time step, member and starting date belongs to. +#' +#'@keywords datagen +#'@examples +#'# See examples on Load() to understand the first lines in this example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' output = 'lonlat', latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'clim <- Clim(sampleMap$mod, sampleMap$obs) +#'ano_exp <- Ano(sampleMap$mod, clim$clim_exp) +#'PB <- ProbBins(ano_exp, fcyr = 3, thr = c(1/3, 2/3), quantile = TRUE, posdates = 3, +#' posdim = 2) +#' +#'@export + +ProbBins_new <- function(data, len = 'all', thr, quantile, sdate_dim = 'sdate', + memb_dim = 'member', + compPeriod = "Full period", ncores) { + + # Check inputs + ## dims + if (is.null(memb_dim) && compPeriod != "Cross-validation") { + dims <- sdate_dim + } else { + dims <- c(sdate_dim, memb_dim) + } + + ## data + if (is.null(data)) { + stop("Parameter 'data' cannot be NULL.") + } + if (!is.numeric(data)) { + stop("Parameter 'data' must be a numeric array.") + } + if (is.null(dim(data))) { #is vector, turn into array + data <- array(data, c(dim = length(data))) + dims <- 'dim' + } + ## forecast year + if (length(len) == 1) { + if (len == 'all') { + if (length(dim(data)) == 1) { + len <- array(1:length(data), length(data)) + names(dim(len)) <- names(dim(data)) + } else { + len <- array(1:dim(data)[sdate_dim], dim(data)[sdate_dim]) + } + } + } + if (compPeriod == "Cross-validation") { + result <- lapply(len, function(x) { + if (quantile) { + thr <- Apply(list(ClimProjDiags::Subset(data, + along = sdate_dim, indices = -x)), target_dims = c(dims), + fun = function(x) {quantile(as.vector(x), probs = thr, + na.rm = TRUE, names = FALSE, type = 8)}, + output_dims = 'bin', ncores = ncores)$output1 + } + data <- ClimProjDiags::Subset(data, along = sdate_dim, indices = x) + Apply(list(data, thr), target_dims = list(c(dims), 'bin'), + fun = .bin, ncores = ncores)$output1 + }) + dims <- c(sdate = length(len), dim(result[[1]])[-1]) + result <- unlist(result) + dim(result) <- dims + } else if (compPeriod == "Without fcyr") { + if (quantile) { + thr <- Apply(list(ClimProjDiags::Subset(data, + along = sdate_dim, indices = -len)), target_dims = c(dims), + fun = function(x) {quantile(as.vector(x), probs = thr, + na.rm = TRUE, names = FALSE, type = 8)}, + output_dims = 'bin', ncores = ncores)$output1 + } + data <- ClimProjDiags::Subset(data, along = sdate_dim, indices = len) + result <- Apply(list(data, thr), target_dims = list(c(dims), 'bin'), + fun = .bin, ncores = ncores)$output1 + } else if (compPeriod == "Full period") { + if (quantile) { + thr <- Apply(list(data), target_dims = c(dims), + fun = function(x) {quantile(as.vector(x), probs = thr, + na.rm = TRUE, names = FALSE, type = 8)}, + output_dims = 'bin', ncores = ncores)$output1 + } + result <- Apply(list(data, thr), target_dims = list(c(dims), 'bin'), + fun = .bin, ncores = ncores)$output1 + } else { + stop("Parameter 'compPeriod' must be one of 'Full period', ", + "'Without fcyr' or 'Cross-validation'.") + } + return(result) +} + +.PBF <- function(data, thr, quantile, dims = c('posdate', 'member'), + ncores) { + if (quantile) { + thr <- Apply(list(data), target_dims = c(dims), + fun = function(x) {quantile(as.vector(x), probs = thr, + na.rm = TRUE, names = FALSE, type = 8)}, + output_dims = 'bin', ncores = ncores)$output1 + } + PBF <- Apply(list(data, thr), target_dims = list(c(dims), 'bin'), + fun = .bin, ncores = ncores)$output1 +} +# data <- array(1:15, c(x = 15)) +# thres <- c(5,10) +.bin <- function(data, thres) { + res <- 1 * (data <= thres[1]) + if (length(thres) > 1) { + res <- c(res, unlist(lapply(2:length(thres), function (i) { + return(1 * ((data > thres[i - 1]) & (data <= thres[i]))) + }))) + } + res <- c(res, 1 * (data > thres[length(thres)])) + dim(res) <- c(dim(data), bin = length(thres) + 1) + return(res) +} -- GitLab From e3971c979214b0192004e9040ea1f02aabad780f Mon Sep 17 00:00:00 2001 From: aho Date: Wed, 21 Apr 2021 17:57:19 +0200 Subject: [PATCH 2/5] Transform ProbBins.R --- NAMESPACE | 1 + R/ProbBins.R | 299 +++++++++++++++++++-------------- man/ProbBins.Rd | 79 +++++++++ tests/testthat/test-ProbBins.R | 159 ++++++++++++++++++ 4 files changed, 408 insertions(+), 130 deletions(-) create mode 100644 man/ProbBins.Rd create mode 100644 tests/testthat/test-ProbBins.R diff --git a/NAMESPACE b/NAMESPACE index 6da8d0c..c3f0a8f 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -34,6 +34,7 @@ export(PlotLayout) export(PlotMatrix) export(PlotSection) export(PlotStereoMap) +export(ProbBins) export(RMS) export(RMSSS) export(RandomWalkTest) diff --git a/R/ProbBins.R b/R/ProbBins.R index b0bc279..0bb8876 100644 --- a/R/ProbBins.R +++ b/R/ProbBins.R @@ -1,29 +1,35 @@ -#'Computes Probabilistic Information of a Forecast Relative to a Threshold or a Quantile +#'Compute probabilistic information of a forecast relative to a threshold or a quantile #' #'Compute probabilistic bins of a set of forecast years ('fcyr') relative to #'the forecast climatology over the whole period of anomalies, optionally excluding #'the selected forecast years ('fcyr') or the forecast year for which the #'probabilistic bins are being computed (see 'compPeriod'). #' -#'@param ano Array of anomalies from Ano().\cr -#' Must be of dimension (nexp/nobs, nmemb, nsdates, nleadtime, nlat, nlon) -#'@param fcyr Indices of the forecast years of the anomalies which to compute -#' the probabilistic bins for, or 'all' to compute the bins for all the -#' years.\cr -#' E.g., c(1:5), c(1, 4), 4 or 'all'. -#'@param thr Values used as thresholds to bin the anomalies. -#'@param quantile If quantile is TRUE (default), the threshold ('thr') -#' are quantiles.\cr -#' If quantile is FALSE the thresholds ('thr') introduced are the absolute -#' thresholds of the bins. -#'@param posdates Position of the dimension in \code{ano} that corresponds to -#' the start dates (default = 3). -#'@param posdim Position of the dimension in \code{ano} which will be combined -#' with 'posdates' to compute the quantiles (default = 2, ensemble members). -#'@param compPeriod Three options: -#' "Full period"/"Without fcyr"/"Cross-validation" (The probabilities are -#' computed with the terciles based on ano/ano with all 'fcyr's -#' removed/cross-validation). The default is "Full period". +#'@param data An numeric array of anomalies with the dimensions 'time_dim' and +#' 'memb_dim' at least. It can be generated by \code{Ano()}. +#'@param thr A numeric vector within range [0, 1] used as the thresholds to bin +#' the anomalies. +#'@param fcyr A numeric vector of the indices of the forecast years (i.e., +#' time_dim) to compute the probabilistic bins for, or 'all' to compute the +#' bins for all the years. E.g., c(1:5), c(1, 4), 4, or 'all'. The default +#' value is 'all'. +#'@param time_dim A character string indicating the dimension along which to +#' compute the probabilistic bins. The default value is 'sdate'. +#'@param memb_dim A character string indicating the name of the member +#' dimension or the dimension to be merged with 'time_dim' for probabilistic +#' calculation. The default value is 'member'. +#'@param quantile A logical value indicating if the thresholds ('thr') are +#' quantiles (TRUE) or the absolute thresholds of the bins (FALSE). The +#' default value is TRUE. +#'@param compPeriod A character string referring to three computation options:\cr +#' "Full period": The probabilities are computed based on 'data';\cr +#' "Without fcyr": The probabilities are computed based on 'data' with all +#' 'fcyr' removed;\cr +#' "Cross-validation": The probabilities are computed based on leave-one-out +#' cross-validation.\cr +#' The default value is "Full period". +#'@param ncores An integer indicating the number of cores to use for parallel +#' computation. The default value is NULL. #' #'@return Array with probabilistic information and dimensions:\cr #' c(length('thr') + 1, length(fcyr), nmemb/nparam, nmod/nexp/nobs, @@ -32,51 +38,27 @@ #' of the 'thr'+1 cathegories the forecast/observation at the corresponding #' grid point, time step, member and starting date belongs to. #' -#'@keywords datagen #'@examples -#'# See examples on Load() to understand the first lines in this example -#' \dontrun{ -#'data_path <- system.file('sample_data', package = 's2dverification') -#'expA <- list(name = 'experiment', path = file.path(data_path, -#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', -#' '$VAR_NAME$_$START_DATE$.nc')) -#'obsX <- list(name = 'observation', path = file.path(data_path, -#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', -#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) -#' -#'# Now we are ready to use Load(). -#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') -#'sampleData <- Load('tos', list(expA), list(obsX), startDates, -#' output = 'lonlat', latmin = 27, latmax = 48, -#' lonmin = -12, lonmax = 40) -#' } -#' \dontshow{ +#'\dontshow{ #'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') -#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), -#' c('observation'), startDates, -#' output = 'lonlat', -#' latmin = 27, latmax = 48, -#' lonmin = -12, lonmax = 40) -#' } +#'sampleData <- s2dv:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#'} #'clim <- Clim(sampleMap$mod, sampleMap$obs) #'ano_exp <- Ano(sampleMap$mod, clim$clim_exp) -#'PB <- ProbBins(ano_exp, fcyr = 3, thr = c(1/3, 2/3), quantile = TRUE, posdates = 3, -#' posdim = 2) +#'PB <- ProbBins(ano_exp, fcyr = 3, thr = c(1/3, 2/3), quantile = TRUE) #' +#'@import multiApply +#'@importFrom abind abind #'@export +ProbBins <- function(data, thr, fcyr = 'all', time_dim = 'sdate', memb_dim = 'member', + quantile = TRUE, compPeriod = "Full period", + ncores = NULL) { -ProbBins_new <- function(data, len = 'all', thr, quantile, sdate_dim = 'sdate', - memb_dim = 'member', - compPeriod = "Full period", ncores) { - - # Check inputs - ## dims - if (is.null(memb_dim) && compPeriod != "Cross-validation") { - dims <- sdate_dim - } else { - dims <- c(sdate_dim, memb_dim) - } - + # Check inputs ## data if (is.null(data)) { stop("Parameter 'data' cannot be NULL.") @@ -84,85 +66,142 @@ ProbBins_new <- function(data, len = 'all', thr, quantile, sdate_dim = 'sdate', if (!is.numeric(data)) { stop("Parameter 'data' must be a numeric array.") } - if (is.null(dim(data))) { #is vector, turn into array - data <- array(data, c(dim = length(data))) - dims <- 'dim' +# if (is.null(dim(data))) { #is vector +# dim(data) <- c(length(data)) +# names(dim(data)) <- time_dim +# } + if(any(is.null(names(dim(data))))| any(nchar(names(dim(data))) == 0)) { + stop("Parameter 'data' must have dimension names.") } - ## forecast year - if (length(len) == 1) { - if (len == 'all') { - if (length(dim(data)) == 1) { - len <- array(1:length(data), length(data)) - names(dim(len)) <- names(dim(data)) - } else { - len <- array(1:dim(data)[sdate_dim], dim(data)[sdate_dim]) - } - } + ## thr + if (!is.numeric(thr) | !is.vector(thr)) { + stop("Parameter 'thr' must be a numeric vector.") + } else if (max(thr) > 1 | min(thr) < 0) { + stop("Parameter 'thr' must be within the range [0, 1].") } - if (compPeriod == "Cross-validation") { - result <- lapply(len, function(x) { - if (quantile) { - thr <- Apply(list(ClimProjDiags::Subset(data, - along = sdate_dim, indices = -x)), target_dims = c(dims), - fun = function(x) {quantile(as.vector(x), probs = thr, - na.rm = TRUE, names = FALSE, type = 8)}, - output_dims = 'bin', ncores = ncores)$output1 - } - data <- ClimProjDiags::Subset(data, along = sdate_dim, indices = x) - Apply(list(data, thr), target_dims = list(c(dims), 'bin'), - fun = .bin, ncores = ncores)$output1 - }) - dims <- c(sdate = length(len), dim(result[[1]])[-1]) - result <- unlist(result) - dim(result) <- dims - } else if (compPeriod == "Without fcyr") { - if (quantile) { - thr <- Apply(list(ClimProjDiags::Subset(data, - along = sdate_dim, indices = -len)), target_dims = c(dims), - fun = function(x) {quantile(as.vector(x), probs = thr, - na.rm = TRUE, names = FALSE, type = 8)}, - output_dims = 'bin', ncores = ncores)$output1 + ## time_dim + if (!is.character(time_dim) | length(time_dim) > 1) { + stop("Parameter 'time_dim' must be a character string.") + } + if (!time_dim %in% names(dim(data))) { + stop("Parameter 'time_dim' is not found in 'data' dimension.") + } + ## memb_dim + if (!is.character(memb_dim) | length(memb_dim) > 1) { + stop("Parameter 'memb_dim' must be a character string.") + } + if (!memb_dim %in% names(dim(data))) { + stop("Parameter 'memb_dim' is not found in 'data' dimension.") + } + ## fcyr + if (fcyr != 'all') { + if (!is.numeric(fcyr) | !is.vector(fcyr)) { + stop("Parameter 'fcyr' must be a numeric vector or 'all'.") + } else if (any(fcyr %% 1 != 0) | min(fcyr) < 1 | max(fcyr) > dim(data)[time_dim]) { + stop(paste0("Parameter 'fcyr' must be the indices of 'time_dim' within ", + "the range [1, ", dim(data)[time_dim], "].")) } - data <- ClimProjDiags::Subset(data, along = sdate_dim, indices = len) - result <- Apply(list(data, thr), target_dims = list(c(dims), 'bin'), - fun = .bin, ncores = ncores)$output1 - } else if (compPeriod == "Full period") { - if (quantile) { - thr <- Apply(list(data), target_dims = c(dims), - fun = function(x) {quantile(as.vector(x), probs = thr, - na.rm = TRUE, names = FALSE, type = 8)}, - output_dims = 'bin', ncores = ncores)$output1 - } - result <- Apply(list(data, thr), target_dims = list(c(dims), 'bin'), - fun = .bin, ncores = ncores)$output1 } else { - stop("Parameter 'compPeriod' must be one of 'Full period', ", - "'Without fcyr' or 'Cross-validation'.") + fcyr <- 1:dim(data)[time_dim] + } + ## quantile + if (!is.logical(quantile) | length(quantile) > 1) { + stop("Parameter 'quantile' must be one logical value.") + } + ## compPeriod + if (length(compPeriod) != 1 | any(!compPeriod %in% c('Full period', 'Without fcyr', 'Cross-validation'))) { + stop("Parameter 'compPeriod' must be either 'Full period', 'Without fcyr', or 'Cross-validation'.") } - return(result) + ## ncores + if (!is.null(ncores)) { + if (!is.numeric(ncores) | ncores %% 1 != 0 | ncores <= 0 | + length(ncores) > 1) { + stop("Parameter 'ncores' must be a positive integer.") + } + } + + ############################### + # Calculate ProbBins + + res <- Apply(list(data), + target_dims = list(c(time_dim, memb_dim)), + output_dims = list(c('bin', time_dim, memb_dim)), + fun = .ProbBins, + thr = thr, fcyr = fcyr, quantile = quantile, + compPeriod = compPeriod, + ncores = ncores)$output1 + + return(res) } - -.PBF <- function(data, thr, quantile, dims = c('posdate', 'member'), - ncores) { - if (quantile) { - thr <- Apply(list(data), target_dims = c(dims), - fun = function(x) {quantile(as.vector(x), probs = thr, - na.rm = TRUE, names = FALSE, type = 8)}, - output_dims = 'bin', ncores = ncores)$output1 + +.ProbBins <- function(data, thr = thr, fcyr = 'all', quantile, compPeriod = "Full period") { + + # data: [sdate, member] + + if (compPeriod != 'Cross-validation') { + # forecast + fore <- data[fcyr, ] + sample_fore <- as.vector(fore) # vector: [fcyr + member] + # hindcast + if (compPeriod == "Full period") { + hind <- data + sample <- as.vector(hind) # vector: [sdate + member] + } else if (compPeriod == "Without fcyr") { + hind <- data[-fcyr, ] + sample <- as.vector(hind) # vector: [sdate - fcyr + member] + } + + # quantiles + if (quantile) { + qum <- quantile(sample, probs = thr, na.rm = TRUE, names = FALSE, + type = 8) # vector: [length(thr)] + } else { + qum <- thr + } + + # PBF: Probabilistic bins of a forecast + # This array contains 0s and 1s that indicate the category where the forecast is. + PBF <- array(counts(c(qum, sample_fore), nbthr = length(thr)), + dim = c(length(thr) + 1, length(fcyr), dim(data)[2])) +# names(dim(PBF)) <- c('bin', 'sdate', 'member') + + return(invisible(PBF)) + + + } else { # Cross-Validation + + result <- NULL + for (iyr in fcyr) { + if (is.null(result)) { + result <- .ProbBins(data, fcyr = iyr, thr = thr, quantile = quantile, + compPeriod = "Without fcyr") # [bin, sdate, member] + } else { + result <- abind::abind(result, .ProbBins(data, fcyr = iyr, thr = thr, + quantile = quantile, + compPeriod = "Without fcyr"), + along = 2) # along sdate + } + } + + return(result) + } - PBF <- Apply(list(data, thr), target_dims = list(c(dims), 'bin'), - fun = .bin, ncores = ncores)$output1 + } -# data <- array(1:15, c(x = 15)) -# thres <- c(5,10) -.bin <- function(data, thres) { - res <- 1 * (data <= thres[1]) - if (length(thres) > 1) { - res <- c(res, unlist(lapply(2:length(thres), function (i) { - return(1 * ((data > thres[i - 1]) & (data <= thres[i]))) - }))) + +# This function assign the values to a category which is limited by the thresholds +# It provides binary information +counts <- function (dat, nbthr) { + thr <- dat[1:nbthr] + data <- dat[nbthr + 1:(length(dat) - nbthr)] + prob <- array(NA, dim = c(nbthr + 1, length(dat) - nbthr)) + prob[1, ] <- 1*(data <= thr[1]) + if (nbthr != 1) { + for (ithr in 2:(nbthr)) { + prob[ithr, ] <- 1 * ((data > thr[ithr - 1]) & (data <= thr[ithr])) + } } - res <- c(res, 1 * (data > thres[length(thres)])) - dim(res) <- c(dim(data), bin = length(thres) + 1) - return(res) + prob[nbthr + 1, ] <- 1 * (data > thr[nbthr]) + return(prob) } + diff --git a/man/ProbBins.Rd b/man/ProbBins.Rd new file mode 100644 index 0000000..9e46690 --- /dev/null +++ b/man/ProbBins.Rd @@ -0,0 +1,79 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ProbBins.R +\name{ProbBins} +\alias{ProbBins} +\title{Compute probabilistic information of a forecast relative to a threshold or a quantile} +\usage{ +ProbBins( + data, + thr, + fcyr = "all", + time_dim = "sdate", + memb_dim = "member", + quantile = TRUE, + compPeriod = "Full period", + ncores = NULL +) +} +\arguments{ +\item{data}{An numeric array of anomalies with the dimensions 'time_dim' and +'memb_dim' at least. It can be generated by \code{Ano()}.} + +\item{thr}{A numeric vector within range [0, 1] used as the thresholds to bin +the anomalies.} + +\item{fcyr}{A numeric vector of the indices of the forecast years (i.e., +time_dim) to compute the probabilistic bins for, or 'all' to compute the +bins for all the years. E.g., c(1:5), c(1, 4), 4, or 'all'. The default +value is 'all'.} + +\item{time_dim}{A character string indicating the dimension along which to +compute the probabilistic bins. The default value is 'sdate'.} + +\item{memb_dim}{A character string indicating the name of the member +dimension or the dimension to be merged with 'time_dim' for probabilistic +calculation. The default value is 'member'.} + +\item{quantile}{A logical value indicating if the thresholds ('thr') are +quantiles (TRUE) or the absolute thresholds of the bins (FALSE). The +default value is TRUE.} + +\item{compPeriod}{A character string referring to three computation options:\cr +"Full period": The probabilities are computed based on 'data';\cr +"Without fcyr": The probabilities are computed based on 'data' with all +'fcyr' removed;\cr +"Cross-validation": The probabilities are computed based on leave-one-out +cross-validation.\cr +The default value is "Full period".} + +\item{ncores}{An integer indicating the number of cores to use for parallel +computation. The default value is NULL.} +} +\value{ +Array with probabilistic information and dimensions:\cr + c(length('thr') + 1, length(fcyr), nmemb/nparam, nmod/nexp/nobs, + nltime, nlat, nlon)\cr + The values along the first dimension take values 0 or 1 depending on which + of the 'thr'+1 cathegories the forecast/observation at the corresponding + grid point, time step, member and starting date belongs to. +} +\description{ +Compute probabilistic bins of a set of forecast years ('fcyr') relative to +the forecast climatology over the whole period of anomalies, optionally excluding +the selected forecast years ('fcyr') or the forecast year for which the +probabilistic bins are being computed (see 'compPeriod'). +} +\examples{ +\dontshow{ +startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +sampleData <- s2dv:::.LoadSampleData('tos', c('experiment'), + c('observation'), startDates, + output = 'lonlat', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) +} +clim <- Clim(sampleMap$mod, sampleMap$obs) +ano_exp <- Ano(sampleMap$mod, clim$clim_exp) +PB <- ProbBins(ano_exp, fcyr = 3, thr = c(1/3, 2/3), quantile = TRUE) + +} diff --git a/tests/testthat/test-ProbBins.R b/tests/testthat/test-ProbBins.R new file mode 100644 index 0000000..83e4f3b --- /dev/null +++ b/tests/testthat/test-ProbBins.R @@ -0,0 +1,159 @@ +context("s2dv::ProbBins tests") + +############################################## + # dat1 + set.seed(1) + dat1 <- array(rnorm(24), dim = c(dataset = 1, member = 3, sdate = 4, ftime = 2)) +############################################## + +test_that("1. Input checks", { + + expect_error( + ProbBins(c()), + "Parameter 'data' cannot be NULL." + ) + expect_error( + ProbBins(c(NA, NA)), + "Parameter 'data' must be a numeric array." + ) + expect_error( + ProbBins(array(1:10, dim = c(2, 5))), + "Parameter 'data' must have dimension names." + ) + # thr + expect_error( + ProbBins(dat1, thr = TRUE), + "Parameter 'thr' must be a numeric vector." + ) + expect_error( + ProbBins(dat1, thr = 1:10), + "Parameter 'thr' must be within the range \\[0, 1\\]." + ) + # time_dim + expect_error( + ProbBins(dat1, thr = c(1/3, 2/3), time_dim = 'time'), + "Parameter 'time_dim' is not found in 'data' dimension." + ) + expect_error( + ProbBins(dat1, thr = c(1/3, 2/3), time_dim = 2), + "Parameter 'time_dim' must be a character string." + ) + # memb_dim + expect_error( + ProbBins(dat1, thr = c(1/3, 2/3), memb_dim = 2), + "Parameter 'memb_dim' must be a character string." + ) + expect_error( + ProbBins(dat1, thr = c(1/3, 2/3), memb_dim = 'ens'), + "Parameter 'memb_dim' is not found in 'data' dimension." + ) + # fcyr + expect_error( + ProbBins(dat1, thr = c(1/3, 2/3), fcyr = 'sdate'), + "Parameter 'fcyr' must be a numeric vector or 'all'." + ) + expect_error( + ProbBins(dat1, thr = c(1/3, 2/3), fcyr = 2:6), + "Parameter 'fcyr' must be the indices of 'time_dim' within the range \\[1, 4\\]." + ) + # quantile + expect_error( + ProbBins(dat1, thr = c(1/3, 2/3), quantile = 0.9), + "Parameter 'quantile' must be one logical value." + ) + # compPeriod + expect_error( + ProbBins(dat1, thr = c(1/3, 2/3), compPeriod = TRUE), + "Parameter 'compPeriod' must be either 'Full period', 'Without fcyr', or 'Cross-validation'." + ) + # ncores + expect_error( + ProbBins(dat1, thr = c(1/3, 2/3), ncores = 0), + "Parameter 'ncores' must be a positive integer." + ) + +}) + + +############################################## +test_that("2. Output checks: dat1", { + +expect_equal( +dim(ProbBins(dat1, thr = c(1/3, 2/3))), +c(bin = 3, sdate = 4, member = 3, dataset = 1, ftime = 2) +) +expect_equal( +dim(ProbBins(dat1, thr = c(0.25, 0.5, 0.75))), +c(bin = 4, sdate = 4, member = 3, dataset = 1, ftime = 2) +) +expect_equal( +dim(ProbBins(dat1, thr = c(0.25, 0.5, 0.75), compPeriod = 'Cross-validation')), +c(bin = 4, sdate = 4, member = 3, dataset = 1, ftime = 2) +) +expect_equal( +dim(ProbBins(dat1, thr = c(0.25, 0.5, 0.75), compPeriod = 'Without fcyr')), +c(bin = 4, sdate = 4, member = 3, dataset = 1, ftime = 2) +) +expect_equal( +length(which(ProbBins(dat1, thr = c(1/3, 2/3)) == 0)), +48 +) +expect_equal( +length(which(ProbBins(dat1, thr = c(1/3, 2/3)) == 1)), +24 +) +expect_equal( +which(ProbBins(dat1, thr = c(1/3, 2/3)) == 1), +c(1, 6, 8, 10, 14, 17, 21, 24, 25, 28, 33, 35, 37, 40, 45, 47, 49, 53, 56, 59, 63, 66, 69, 70) +) +expect_equal( +all(is.na(ProbBins(dat1, thr = c(1/3, 2/3), compPeriod = 'Without fcyr'))), +TRUE +) +expect_equal( +dim(ProbBins(dat1, thr = c(1/3, 2/3), fcyr = 2, compPeriod = 'Without fcyr')), +c(bin = 3, sdate = 1, member = 3, dataset = 1, ftime = 2) +) +expect_equal( +length(which(ProbBins(dat1, thr = c(1/3, 2/3), fcyr = 2, compPeriod = 'Without fcyr') == 0)), +12 +) +expect_equal( +length(which(ProbBins(dat1, thr = c(1/3, 2/3), fcyr = 2, compPeriod = 'Without fcyr') == 1)), +6 +) +expect_equal( +which(ProbBins(dat1, thr = c(1/3, 2/3), fcyr = 2, compPeriod = 'Without fcyr') == 1), +c(3, 5, 7, 11, 14, 18) +) +expect_equal( +length(which(ProbBins(dat1, thr = c(1/3, 2/3), fcyr = 2, compPeriod = 'Cross-validation') == 0)), +12 +) +expect_equal( +length(which(ProbBins(dat1, thr = c(1/3, 2/3), fcyr = 2, compPeriod = 'Cross-validation') == 1)), +6 +) +expect_equal( +which(ProbBins(dat1, thr = c(1/3, 2/3), fcyr = 2, compPeriod = 'Cross-validation') == 1), +c(3, 5, 7, 11, 14, 18) +) + +expect_equal( +dim(ProbBins(dat1, thr = c(1/3, 2/3), quantile = FALSE)), +c(bin = 3, sdate = 4, member = 3, dataset = 1, ftime = 2) +) +expect_equal( +length(which(ProbBins(dat1, thr = c(1/3, 2/3), quantile = FALSE) == 0)), +48 +) +expect_equal( +length(which(ProbBins(dat1, thr = c(1/3, 2/3), quantile = FALSE) == 1)), +24 +) +expect_equal( +which(ProbBins(dat1, thr = c(1/3, 2/3), quantile = FALSE) == 1), +c(1, 6, 8, 10, 13, 16, 21, 24, 25, 28, 32, 35, 37, 40, 45, 48, 49, 52, 56, 58, 63, 66, 69, 70) +) + +}) -- GitLab From c3635761c30f56ba77a5b40b258398f3a2125ef7 Mon Sep 17 00:00:00 2001 From: aho Date: Wed, 21 Apr 2021 17:57:41 +0200 Subject: [PATCH 3/5] Update documents --- DESCRIPTION | 2 +- man/AMV.Rd | 21 ++++++-- man/AnimateMap.Rd | 33 +++++++++--- man/Ano.Rd | 1 - man/Clim.Rd | 16 ++++-- man/ColorBar.Rd | 32 +++++++++--- man/Composite.Rd | 14 +++-- man/ConfigApplyMatchingEntries.Rd | 11 ++-- man/ConfigEditDefinition.Rd | 1 - man/ConfigEditEntry.Rd | 45 ++++++++++++---- man/ConfigFileOpen.Rd | 3 +- man/ConfigShowSimilarEntries.Rd | 17 ++++-- man/ConfigShowTable.Rd | 3 +- man/Corr.Rd | 17 ++++-- man/Eno.Rd | 1 - man/GMST.Rd | 24 +++++++-- man/GSAT.Rd | 21 ++++++-- man/InsertDim.Rd | 1 - man/LeapYear.Rd | 1 - man/Load.Rd | 40 ++++++++++---- man/MeanDims.Rd | 3 +- man/Persistence.Rd | 17 ++++-- man/PlotAno.Rd | 31 ++++++++--- man/PlotClim.Rd | 26 +++++++--- man/PlotEquiMap.Rd | 86 ++++++++++++++++++++++++------- man/PlotLayout.Rd | 73 ++++++++++++++++++-------- man/PlotMatrix.Rd | 29 ++++++++--- man/PlotSection.Rd | 25 +++++++-- man/PlotStereoMap.Rd | 61 +++++++++++++++++----- man/RMS.Rd | 14 +++-- man/RMSSS.Rd | 11 ++-- man/RandomWalkTest.Rd | 1 - man/Regression.Rd | 14 +++-- man/Reorder.Rd | 1 - man/SPOD.Rd | 21 ++++++-- man/Season.Rd | 13 +++-- man/Smoothing.Rd | 1 - man/TPI.Rd | 21 ++++++-- man/ToyModel.Rd | 15 ++++-- man/Trend.Rd | 13 +++-- man/clim.palette.Rd | 3 +- man/s2dv-package.Rd | 47 +++++++++++++---- man/sampleDepthData.Rd | 1 - man/sampleMap.Rd | 1 - man/sampleTimeSeries.Rd | 1 - 45 files changed, 620 insertions(+), 213 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 126179a..30fd237 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -45,4 +45,4 @@ BugReports: https://earth.bsc.es/gitlab/es/s2dv/-/issues LazyData: true SystemRequirements: cdo Encoding: UTF-8 -RoxygenNote: 5.0.0 +RoxygenNote: 7.0.1 diff --git a/man/AMV.Rd b/man/AMV.Rd index 5aa6d30..881e136 100644 --- a/man/AMV.Rd +++ b/man/AMV.Rd @@ -4,10 +4,22 @@ \alias{AMV} \title{Compute the Atlantic Multidecadal Variability (AMV) index} \usage{ -AMV(data, data_lats, data_lons, type, lat_dim = "lat", lon_dim = "lon", - mask = NULL, monini = 11, fmonth_dim = "fmonth", sdate_dim = "sdate", - indices_for_clim = NULL, year_dim = "year", month_dim = "month", - member_dim = "member") +AMV( + data, + data_lats, + data_lons, + type, + lat_dim = "lat", + lon_dim = "lon", + mask = NULL, + monini = 11, + fmonth_dim = "fmonth", + sdate_dim = "sdate", + indices_for_clim = NULL, + year_dim = "year", + month_dim = "month", + member_dim = "member" +) } \arguments{ \item{data}{A numerical array to be used for the index computation with the @@ -106,4 +118,3 @@ lon <- seq(0, 360, 10) index_dcpp <- AMV(data = dcpp, data_lats = lat, data_lons = lon, type = 'dcpp', monini = 1) } - diff --git a/man/AnimateMap.Rd b/man/AnimateMap.Rd index d2003ee..2ec930d 100644 --- a/man/AnimateMap.Rd +++ b/man/AnimateMap.Rd @@ -4,13 +4,33 @@ \alias{AnimateMap} \title{Animate Maps of Forecast/Observed Values or Scores Over Forecast Time} \usage{ -AnimateMap(var, lon, lat, toptitle = rep("", 11), sizetit = 1, units = "", - monini = 1, freq = 12, msk95lev = FALSE, brks = NULL, cols = NULL, - filled.continents = FALSE, lonmin = 0, lonmax = 360, latmin = -90, - latmax = 90, intlon = 20, intlat = 30, drawleg = TRUE, - subsampleg = 1, colNA = "white", equi = TRUE, +AnimateMap( + var, + lon, + lat, + toptitle = rep("", 11), + sizetit = 1, + units = "", + monini = 1, + freq = 12, + msk95lev = FALSE, + brks = NULL, + cols = NULL, + filled.continents = FALSE, + lonmin = 0, + lonmax = 360, + latmin = -90, + latmax = 90, + intlon = 20, + intlat = 30, + drawleg = TRUE, + subsampleg = 1, + colNA = "white", + equi = TRUE, fileout = c("output1_animvsltime.gif", "output2_animvsltime.gif", - "output3_animvsltime.gif"), ...) + "output3_animvsltime.gif"), + ... +) } \arguments{ \item{var}{Matrix of dimensions (nltime, nlat, nlon) or @@ -162,4 +182,3 @@ AnimateMap(clim$clim_exp, sampleData$lon, sampleData$lat, # More examples in s2dverification but are deleted for now } - diff --git a/man/Ano.Rd b/man/Ano.Rd index 2dd4dea..8e423af 100644 --- a/man/Ano.Rd +++ b/man/Ano.Rd @@ -41,4 +41,3 @@ PlotAno(ano_exp, ano_obs, startDates, legends = 'ERSST', biglab = FALSE, fileout = 'tos_ano.png') } } - diff --git a/man/Clim.Rd b/man/Clim.Rd index a997a7f..78559bd 100644 --- a/man/Clim.Rd +++ b/man/Clim.Rd @@ -4,9 +4,18 @@ \alias{Clim} \title{Compute Bias Corrected Climatologies} \usage{ -Clim(exp, obs, time_dim = "sdate", dat_dim = c("dataset", "member"), - method = "clim", ftime_dim = "ftime", memb = TRUE, - memb_dim = "member", na.rm = TRUE, ncores = NULL) +Clim( + exp, + obs, + time_dim = "sdate", + dat_dim = c("dataset", "member"), + method = "clim", + ftime_dim = "ftime", + memb = TRUE, + memb_dim = "member", + na.rm = TRUE, + ncores = NULL +) } \arguments{ \item{exp}{A named numeric array of experimental data, with at least two @@ -82,4 +91,3 @@ PlotClim(clim$clim_exp, clim$clim_obs, listobs = c('ERSST'), biglab = FALSE, fileout = 'tos_clim.eps') } } - diff --git a/man/ColorBar.Rd b/man/ColorBar.Rd index 1287b70..6d62f15 100644 --- a/man/ColorBar.Rd +++ b/man/ColorBar.Rd @@ -4,13 +4,30 @@ \alias{ColorBar} \title{Draws a Color Bar} \usage{ -ColorBar(brks = NULL, cols = NULL, vertical = TRUE, subsampleg = NULL, - bar_limits = NULL, var_limits = NULL, triangle_ends = NULL, - col_inf = NULL, col_sup = NULL, color_fun = clim.palette(), - plot = TRUE, draw_ticks = TRUE, draw_separators = FALSE, - triangle_ends_scale = 1, extra_labels = NULL, title = NULL, - title_scale = 1, label_scale = 1, tick_scale = 1, - extra_margin = rep(0, 4), label_digits = 4, ...) +ColorBar( + brks = NULL, + cols = NULL, + vertical = TRUE, + subsampleg = NULL, + bar_limits = NULL, + var_limits = NULL, + triangle_ends = NULL, + col_inf = NULL, + col_sup = NULL, + color_fun = clim.palette(), + plot = TRUE, + draw_ticks = TRUE, + draw_separators = FALSE, + triangle_ends_scale = 1, + extra_labels = NULL, + title = NULL, + title_scale = 1, + label_scale = 1, + tick_scale = 1, + extra_margin = rep(0, 4), + label_digits = 4, + ... +) } \arguments{ \item{brks}{Can be provided in two formats: @@ -175,4 +192,3 @@ cols <- c("dodgerblue4", "dodgerblue1", "forestgreen", "yellowgreen", "white", lims <- seq(-1, 1, 0.2) ColorBar(lims, cols) } - diff --git a/man/Composite.Rd b/man/Composite.Rd index 64d5bfc..cc21d38 100644 --- a/man/Composite.Rd +++ b/man/Composite.Rd @@ -4,8 +4,17 @@ \alias{Composite} \title{Compute composites} \usage{ -Composite(data, occ, time_dim = "time", space_dim = c("lon", "lat"), - lag = 0, eno = FALSE, K = NULL, fileout = NULL, ncores = NULL) +Composite( + data, + occ, + time_dim = "time", + space_dim = c("lon", "lat"), + lag = 0, + eno = FALSE, + K = NULL, + fileout = NULL, + ncores = NULL +) } \arguments{ \item{data}{A numeric array containing two spatial and one temporal @@ -101,4 +110,3 @@ occ <- c(1, 1, 2, 2, 3, 3) res <- Composite(data, occ, time_dim = 'case', K = 4) } - diff --git a/man/ConfigApplyMatchingEntries.Rd b/man/ConfigApplyMatchingEntries.Rd index 5f0efb1..ee4cb5a 100644 --- a/man/ConfigApplyMatchingEntries.Rd +++ b/man/ConfigApplyMatchingEntries.Rd @@ -4,8 +4,14 @@ \alias{ConfigApplyMatchingEntries} \title{Apply Matching Entries To Dataset Name And Variable Name To Find Related Info} \usage{ -ConfigApplyMatchingEntries(configuration, var, exp = NULL, obs = NULL, - show_entries = FALSE, show_result = TRUE) +ConfigApplyMatchingEntries( + configuration, + var, + exp = NULL, + obs = NULL, + show_entries = FALSE, + show_result = TRUE +) } \arguments{ \item{configuration}{Configuration object obtained from ConfigFileOpen() @@ -68,4 +74,3 @@ ConfigApplyMatchingEntries, ConfigEditDefinition, ConfigEditEntry, ConfigFileOpen, ConfigShowSimilarEntries, ConfigShowTable } - diff --git a/man/ConfigEditDefinition.Rd b/man/ConfigEditDefinition.Rd index 8e1e968..223e95a 100644 --- a/man/ConfigEditDefinition.Rd +++ b/man/ConfigEditDefinition.Rd @@ -57,4 +57,3 @@ match_info <- ConfigApplyMatchingEntries(configuration, 'tas', [ConfigEditEntry()], [ConfigFileOpen()], [ConfigShowSimilarEntries()], [ConfigShowTable()]. } - diff --git a/man/ConfigEditEntry.Rd b/man/ConfigEditEntry.Rd index 9abf3e5..e597709 100644 --- a/man/ConfigEditEntry.Rd +++ b/man/ConfigEditEntry.Rd @@ -1,22 +1,46 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/ConfigEditEntry.R \name{ConfigEditEntry} -\alias{ConfigAddEntry} \alias{ConfigEditEntry} +\alias{ConfigAddEntry} \alias{ConfigRemoveEntry} \title{Add, Remove Or Edit Entries In The Configuration} \usage{ -ConfigEditEntry(configuration, dataset_type, position, dataset_name = NULL, - var_name = NULL, main_path = NULL, file_path = NULL, - nc_var_name = NULL, suffix = NULL, varmin = NULL, varmax = NULL) +ConfigEditEntry( + configuration, + dataset_type, + position, + dataset_name = NULL, + var_name = NULL, + main_path = NULL, + file_path = NULL, + nc_var_name = NULL, + suffix = NULL, + varmin = NULL, + varmax = NULL +) -ConfigAddEntry(configuration, dataset_type, position = "last", - dataset_name = ".*", var_name = ".*", main_path = "*", - file_path = "*", nc_var_name = "*", suffix = "*", varmin = "*", - varmax = "*") +ConfigAddEntry( + configuration, + dataset_type, + position = "last", + dataset_name = ".*", + var_name = ".*", + main_path = "*", + file_path = "*", + nc_var_name = "*", + suffix = "*", + varmin = "*", + varmax = "*" +) -ConfigRemoveEntry(configuration, dataset_type, dataset_name = NULL, - var_name = NULL, position = NULL) +ConfigRemoveEntry( + configuration, + dataset_type, + dataset_name = NULL, + var_name = NULL, + position = NULL +) } \arguments{ \item{configuration}{Configuration object obtained via ConfigFileOpen() @@ -99,4 +123,3 @@ ConfigFileSave(configuration, config_file, confirm = FALSE) ConfigApplyMatchingEntries, ConfigEditDefinition, ConfigEditEntry, ConfigFileOpen, ConfigShowSimilarEntries, ConfigShowTable } - diff --git a/man/ConfigFileOpen.Rd b/man/ConfigFileOpen.Rd index eee183f..893900b 100644 --- a/man/ConfigFileOpen.Rd +++ b/man/ConfigFileOpen.Rd @@ -1,8 +1,8 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/ConfigFileOpen.R \name{ConfigFileOpen} -\alias{ConfigFileCreate} \alias{ConfigFileOpen} +\alias{ConfigFileCreate} \alias{ConfigFileSave} \title{Functions To Create Open And Save Configuration File} \usage{ @@ -194,4 +194,3 @@ ConfigFileSave(configuration, config_file, confirm = FALSE) ConfigApplyMatchingEntries, ConfigEditDefinition, ConfigEditEntry, ConfigFileOpen, ConfigShowSimilarEntries, ConfigShowTable } - diff --git a/man/ConfigShowSimilarEntries.Rd b/man/ConfigShowSimilarEntries.Rd index b9f80ce..72b77e1 100644 --- a/man/ConfigShowSimilarEntries.Rd +++ b/man/ConfigShowSimilarEntries.Rd @@ -4,10 +4,18 @@ \alias{ConfigShowSimilarEntries} \title{Find Similar Entries In Tables Of Datasets} \usage{ -ConfigShowSimilarEntries(configuration, dataset_name = NULL, - var_name = NULL, main_path = NULL, file_path = NULL, - nc_var_name = NULL, suffix = NULL, varmin = NULL, varmax = NULL, - n_results = 10) +ConfigShowSimilarEntries( + configuration, + dataset_name = NULL, + var_name = NULL, + main_path = NULL, + file_path = NULL, + nc_var_name = NULL, + suffix = NULL, + varmin = NULL, + varmax = NULL, + n_results = 10 +) } \arguments{ \item{configuration}{Configuration object obtained either from @@ -79,4 +87,3 @@ ConfigShowSimilarEntries(configuration, dataset_name = "Exper", ConfigApplyMatchingEntries, ConfigEditDefinition, ConfigEditEntry, ConfigFileOpen, ConfigShowSimilarEntries, ConfigShowTable } - diff --git a/man/ConfigShowTable.Rd b/man/ConfigShowTable.Rd index 7c08053..5e4172a 100644 --- a/man/ConfigShowTable.Rd +++ b/man/ConfigShowTable.Rd @@ -1,8 +1,8 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/ConfigShowTable.R \name{ConfigShowTable} -\alias{ConfigShowDefinitions} \alias{ConfigShowTable} +\alias{ConfigShowDefinitions} \title{Show Configuration Tables And Definitions} \usage{ ConfigShowTable(configuration, dataset_type, line_numbers = NULL) @@ -54,4 +54,3 @@ ConfigShowDefinitions(configuration) [ConfigEditEntry()], [ConfigFileOpen()], [ConfigShowSimilarEntries()], [ConfigShowTable()]. } - diff --git a/man/Corr.Rd b/man/Corr.Rd index bf5575e..9c20ec1 100644 --- a/man/Corr.Rd +++ b/man/Corr.Rd @@ -4,9 +4,19 @@ \alias{Corr} \title{Compute the correlation coefficient between an array of forecast and their corresponding observation} \usage{ -Corr(exp, obs, time_dim = "sdate", dat_dim = "dataset", comp_dim = NULL, - limits = NULL, method = "pearson", pval = TRUE, conf = TRUE, - conf.lev = 0.95, ncores = NULL) +Corr( + exp, + obs, + time_dim = "sdate", + dat_dim = "dataset", + comp_dim = NULL, + limits = NULL, + method = "pearson", + pval = TRUE, + conf = TRUE, + conf.lev = 0.95, + ncores = NULL +) } \arguments{ \item{exp}{A named numeric array of experimental data, with at least two @@ -86,4 +96,3 @@ corr <- Corr(clim$clim_exp, clim$clim_obs, time_dim = 'ftime', dat_dim = 'member # Renew the example when Ano and Smoothing is ready } - diff --git a/man/Eno.Rd b/man/Eno.Rd index 32468bd..03c3b4f 100644 --- a/man/Eno.Rd +++ b/man/Eno.Rd @@ -39,4 +39,3 @@ data[na] <- NA res <- Eno(data) } - diff --git a/man/GMST.Rd b/man/GMST.Rd index 208ff75..03d1092 100644 --- a/man/GMST.Rd +++ b/man/GMST.Rd @@ -4,10 +4,25 @@ \alias{GMST} \title{Compute the Global Mean Surface Temperature (GMST) anomalies} \usage{ -GMST(data_tas, data_tos, data_lats, data_lons, mask_sea_land, sea_value, type, - mask = NULL, lat_dim = "lat", lon_dim = "lon", monini = 11, - fmonth_dim = "fmonth", sdate_dim = "sdate", indices_for_clim = NULL, - year_dim = "year", month_dim = "month", member_dim = "member") +GMST( + data_tas, + data_tos, + data_lats, + data_lons, + mask_sea_land, + sea_value, + type, + mask = NULL, + lat_dim = "lat", + lon_dim = "lon", + monini = 11, + fmonth_dim = "fmonth", + sdate_dim = "sdate", + indices_for_clim = NULL, + year_dim = "year", + month_dim = "month", + member_dim = "member" +) } \arguments{ \item{data_tas}{A numerical array indicating the surface air temperature data @@ -134,4 +149,3 @@ index_dcpp <- GMST(data_tas = dcpp_tas, data_tos = dcpp_tos, data_lats = lat, sea_value = sea_value) } - diff --git a/man/GSAT.Rd b/man/GSAT.Rd index 9d3fbb6..370900d 100644 --- a/man/GSAT.Rd +++ b/man/GSAT.Rd @@ -4,10 +4,22 @@ \alias{GSAT} \title{Compute the Global Surface Air Temperature (GSAT) anomalies} \usage{ -GSAT(data, data_lats, data_lons, type, lat_dim = "lat", lon_dim = "lon", - mask = NULL, monini = 11, fmonth_dim = "fmonth", sdate_dim = "sdate", - indices_for_clim = NULL, year_dim = "year", month_dim = "month", - member_dim = "member") +GSAT( + data, + data_lats, + data_lons, + type, + lat_dim = "lat", + lon_dim = "lon", + mask = NULL, + monini = 11, + fmonth_dim = "fmonth", + sdate_dim = "sdate", + indices_for_clim = NULL, + year_dim = "year", + month_dim = "month", + member_dim = "member" +) } \arguments{ \item{data}{A numerical array to be used for the index computation with the @@ -101,4 +113,3 @@ lon <- seq(0, 360, 10) index_dcpp <- GSAT(data = dcpp, data_lats = lat, data_lons = lon, type = 'dcpp', monini = 1) } - diff --git a/man/InsertDim.Rd b/man/InsertDim.Rd index 8ab628d..c0dd7d8 100644 --- a/man/InsertDim.Rd +++ b/man/InsertDim.Rd @@ -32,4 +32,3 @@ res <- InsertDim(InsertDim(a, posdim = 2, lendim = 1, name = 'e'), 4, c(f = 2)) dim(res) } - diff --git a/man/LeapYear.Rd b/man/LeapYear.Rd index d261b0a..c2960f3 100644 --- a/man/LeapYear.Rd +++ b/man/LeapYear.Rd @@ -21,4 +21,3 @@ print(LeapYear(1991)) print(LeapYear(1992)) print(LeapYear(1993)) } - diff --git a/man/Load.Rd b/man/Load.Rd index 214f984..10c03f9 100644 --- a/man/Load.Rd +++ b/man/Load.Rd @@ -4,15 +4,36 @@ \alias{Load} \title{Loads Experimental And Observational Data} \usage{ -Load(var, exp = NULL, obs = NULL, sdates, nmember = NULL, - nmemberobs = NULL, nleadtime = NULL, leadtimemin = 1, - leadtimemax = NULL, storefreq = "monthly", sampleperiod = 1, - lonmin = 0, lonmax = 360, latmin = -90, latmax = 90, - output = "areave", method = "conservative", grid = NULL, - maskmod = vector("list", 15), maskobs = vector("list", 15), - configfile = NULL, varmin = NULL, varmax = NULL, silent = FALSE, - nprocs = NULL, dimnames = NULL, remapcells = 2, - path_glob_permissive = "partial") +Load( + var, + exp = NULL, + obs = NULL, + sdates, + nmember = NULL, + nmemberobs = NULL, + nleadtime = NULL, + leadtimemin = 1, + leadtimemax = NULL, + storefreq = "monthly", + sampleperiod = 1, + lonmin = 0, + lonmax = 360, + latmin = -90, + latmax = 90, + output = "areave", + method = "conservative", + grid = NULL, + maskmod = vector("list", 15), + maskobs = vector("list", 15), + configfile = NULL, + varmin = NULL, + varmax = NULL, + silent = FALSE, + nprocs = NULL, + dimnames = NULL, + remapcells = 2, + path_glob_permissive = "partial" +) } \arguments{ \item{var}{Short name of the variable to load. It should coincide with the @@ -874,4 +895,3 @@ sampleData <- s2dv:::.LoadSampleData('tos', c('experiment'), lonmin = -12, lonmax = 40) } } - diff --git a/man/MeanDims.Rd b/man/MeanDims.Rd index f200023..9c874fc 100644 --- a/man/MeanDims.Rd +++ b/man/MeanDims.Rd @@ -4,7 +4,7 @@ \alias{MeanDims} \title{Average an array along multiple dimensions} \usage{ -MeanDims(data, dims, na.rm = TRUE, ncores = NULL) +MeanDims(data, dims, na.rm = FALSE, ncores = NULL) } \arguments{ \item{data}{An array to be averaged.} @@ -39,4 +39,3 @@ History:\cr 3.0 - 2020-01 (A. Ho, \email{an.ho@bsc.es}) - Preserve dimension names } \keyword{datagen} - diff --git a/man/Persistence.Rd b/man/Persistence.Rd index 33d4868..3582633 100644 --- a/man/Persistence.Rd +++ b/man/Persistence.Rd @@ -4,9 +4,19 @@ \alias{Persistence} \title{Compute persistence} \usage{ -Persistence(data, dates, time_dim = "time", start, end, ft_start, - ft_end = ft_start, max_ft = 10, nmemb = 1, na.action = 10, - ncores = NULL) +Persistence( + data, + dates, + time_dim = "time", + start, + end, + ft_start, + ft_end = ft_start, + max_ft = 10, + nmemb = 1, + na.action = 10, + ncores = NULL +) } \arguments{ \item{data}{A numeric array corresponding to the observational data @@ -98,4 +108,3 @@ persist <- Persistence(obs1, dates = dates, start = 1961, end = 2005, ft_start = nmemb = 40) } - diff --git a/man/PlotAno.Rd b/man/PlotAno.Rd index 18bf0c9..6591ef1 100644 --- a/man/PlotAno.Rd +++ b/man/PlotAno.Rd @@ -4,12 +4,30 @@ \alias{PlotAno} \title{Plot Anomaly time series} \usage{ -PlotAno(exp_ano, obs_ano = NULL, sdates, toptitle = rep("", 15), - ytitle = rep("", 15), limits = NULL, legends = NULL, freq = 12, - biglab = FALSE, fill = TRUE, memb = TRUE, ensmean = TRUE, - linezero = FALSE, points = FALSE, vlines = NULL, sizetit = 1, - fileout = NULL, width = 8, height = 5, size_units = "in", res = 100, - ...) +PlotAno( + exp_ano, + obs_ano = NULL, + sdates, + toptitle = rep("", 15), + ytitle = rep("", 15), + limits = NULL, + legends = NULL, + freq = 12, + biglab = FALSE, + fill = TRUE, + memb = TRUE, + ensmean = TRUE, + linezero = FALSE, + points = FALSE, + vlines = NULL, + sizetit = 1, + fileout = NULL, + width = 8, + height = 5, + size_units = "in", + res = 100, + ... +) } \arguments{ \item{exp_ano}{A numerical array containing the experimental data:\cr @@ -100,4 +118,3 @@ PlotAno(smooth_ano_exp, smooth_ano_obs, startDates, legends = 'ERSST', biglab = FALSE) } - diff --git a/man/PlotClim.Rd b/man/PlotClim.Rd index b62ff44..9b3381e 100644 --- a/man/PlotClim.Rd +++ b/man/PlotClim.Rd @@ -4,11 +4,26 @@ \alias{PlotClim} \title{Plots Climatologies} \usage{ -PlotClim(exp_clim, obs_clim = NULL, toptitle = "", ytitle = "", - monini = 1, freq = 12, limits = NULL, listexp = c("exp1", "exp2", - "exp3"), listobs = c("obs1", "obs2", "obs3"), biglab = FALSE, - leg = TRUE, sizetit = 1, fileout = NULL, width = 8, height = 5, - size_units = "in", res = 100, ...) +PlotClim( + exp_clim, + obs_clim = NULL, + toptitle = "", + ytitle = "", + monini = 1, + freq = 12, + limits = NULL, + listexp = c("exp1", "exp2", "exp3"), + listobs = c("obs1", "obs2", "obs3"), + biglab = FALSE, + leg = TRUE, + sizetit = 1, + fileout = NULL, + width = 8, + height = 5, + size_units = "in", + res = 100, + ... +) } \arguments{ \item{exp_clim}{Matrix containing the experimental data with dimensions:\cr @@ -79,4 +94,3 @@ PlotClim(clim$clim_exp, clim$clim_obs, toptitle = paste('climatologies'), listobs = c('ERSST'), biglab = FALSE, fileout = NULL) } - diff --git a/man/PlotEquiMap.Rd b/man/PlotEquiMap.Rd index cf45ead..fbd7042 100644 --- a/man/PlotEquiMap.Rd +++ b/man/PlotEquiMap.Rd @@ -4,25 +4,72 @@ \alias{PlotEquiMap} \title{Maps A Two-Dimensional Variable On A Cylindrical Equidistant Projection} \usage{ -PlotEquiMap(var, lon, lat, varu = NULL, varv = NULL, toptitle = NULL, - sizetit = NULL, units = NULL, brks = NULL, cols = NULL, - bar_limits = NULL, triangle_ends = NULL, col_inf = NULL, - col_sup = NULL, colNA = NULL, color_fun = clim.palette(), - square = TRUE, filled.continents = NULL, coast_color = NULL, - coast_width = 1, contours = NULL, brks2 = NULL, contour_lwd = 0.5, - contour_color = "black", contour_lty = 1, contour_label_scale = 1, - dots = NULL, dot_symbol = 4, dot_size = 1, - arr_subsamp = floor(length(lon)/30), arr_scale = 1, arr_ref_len = 15, - arr_units = "m/s", arr_scale_shaft = 1, arr_scale_shaft_angle = 1, - axelab = TRUE, labW = FALSE, intylat = 20, intxlon = 20, - axes_tick_scale = 1, axes_label_scale = 1, drawleg = TRUE, - subsampleg = NULL, bar_extra_labels = NULL, draw_bar_ticks = TRUE, - draw_separators = FALSE, triangle_ends_scale = 1, bar_label_digits = 4, - bar_label_scale = 1, units_scale = 1, bar_tick_scale = 1, - bar_extra_margin = rep(0, 4), boxlim = NULL, boxcol = "purple2", - boxlwd = 5, margin_scale = rep(1, 4), title_scale = 1, numbfig = NULL, - fileout = NULL, width = 8, height = 5, size_units = "in", res = 100, - ...) +PlotEquiMap( + var, + lon, + lat, + varu = NULL, + varv = NULL, + toptitle = NULL, + sizetit = NULL, + units = NULL, + brks = NULL, + cols = NULL, + bar_limits = NULL, + triangle_ends = NULL, + col_inf = NULL, + col_sup = NULL, + colNA = NULL, + color_fun = clim.palette(), + square = TRUE, + filled.continents = NULL, + coast_color = NULL, + coast_width = 1, + contours = NULL, + brks2 = NULL, + contour_lwd = 0.5, + contour_color = "black", + contour_lty = 1, + contour_label_scale = 1, + dots = NULL, + dot_symbol = 4, + dot_size = 1, + arr_subsamp = floor(length(lon)/30), + arr_scale = 1, + arr_ref_len = 15, + arr_units = "m/s", + arr_scale_shaft = 1, + arr_scale_shaft_angle = 1, + axelab = TRUE, + labW = FALSE, + intylat = 20, + intxlon = 20, + axes_tick_scale = 1, + axes_label_scale = 1, + drawleg = TRUE, + subsampleg = NULL, + bar_extra_labels = NULL, + draw_bar_ticks = TRUE, + draw_separators = FALSE, + triangle_ends_scale = 1, + bar_label_digits = 4, + bar_label_scale = 1, + units_scale = 1, + bar_tick_scale = 1, + bar_extra_margin = rep(0, 4), + boxlim = NULL, + boxcol = "purple2", + boxlwd = 5, + margin_scale = rep(1, 4), + title_scale = 1, + numbfig = NULL, + fileout = NULL, + width = 8, + height = 5, + size_units = "in", + res = 100, + ... +) } \arguments{ \item{var}{Array with the values at each cell of a grid on a regular @@ -278,4 +325,3 @@ PlotEquiMap(sampleData$mod[1, 1, 1, 1, , ], sampleData$lon, sampleData$lat, toptitle = 'Predicted sea surface temperature for Nov 1960 from 1st Nov', sizetit = 0.5) } - diff --git a/man/PlotLayout.Rd b/man/PlotLayout.Rd index f01fdf9..453cf2e 100644 --- a/man/PlotLayout.Rd +++ b/man/PlotLayout.Rd @@ -4,20 +4,52 @@ \alias{PlotLayout} \title{Arrange and Fill Multi-Pannel Layouts With Optional Colour Bar} \usage{ -PlotLayout(fun, plot_dims, var, ..., special_args = NULL, nrow = NULL, - ncol = NULL, toptitle = NULL, row_titles = NULL, col_titles = NULL, - bar_scale = 1, title_scale = 1, title_margin_scale = 1, - title_left_shift_scale = 1, subtitle_scale = 1, - subtitle_margin_scale = 1, brks = NULL, cols = NULL, drawleg = "S", - titles = NULL, subsampleg = NULL, bar_limits = NULL, - triangle_ends = NULL, col_inf = NULL, col_sup = NULL, - color_fun = clim.colors, draw_bar_ticks = TRUE, draw_separators = FALSE, - triangle_ends_scale = 1, bar_extra_labels = NULL, units = NULL, - units_scale = 1, bar_label_scale = 1, bar_tick_scale = 1, - bar_extra_margin = rep(0, 4), bar_left_shift_scale = 1, - bar_label_digits = 4, extra_margin = rep(0, 4), fileout = NULL, - width = NULL, height = NULL, size_units = "in", res = 100, - close_device = TRUE) +PlotLayout( + fun, + plot_dims, + var, + ..., + special_args = NULL, + nrow = NULL, + ncol = NULL, + toptitle = NULL, + row_titles = NULL, + col_titles = NULL, + bar_scale = 1, + title_scale = 1, + title_margin_scale = 1, + title_left_shift_scale = 1, + subtitle_scale = 1, + subtitle_margin_scale = 1, + brks = NULL, + cols = NULL, + drawleg = "S", + titles = NULL, + subsampleg = NULL, + bar_limits = NULL, + triangle_ends = NULL, + col_inf = NULL, + col_sup = NULL, + color_fun = clim.colors, + draw_bar_ticks = TRUE, + draw_separators = FALSE, + triangle_ends_scale = 1, + bar_extra_labels = NULL, + units = NULL, + units_scale = 1, + bar_label_scale = 1, + bar_tick_scale = 1, + bar_extra_margin = rep(0, 4), + bar_left_shift_scale = 1, + bar_label_digits = 4, + extra_margin = rep(0, 4), + fileout = NULL, + width = NULL, + height = NULL, + size_units = "in", + res = 100, + close_device = TRUE +) } \arguments{ \item{fun}{Plot function (or name of the function) to be called on the @@ -48,6 +80,12 @@ applied to each of them. NAs can be passed to the list: a NA will yield a blank cell in the layout, which can be populated after (see .SwitchToFigure).} +\item{\dots}{Parameters to be sent to the plotting function 'fun'. If +multiple arrays are provided in 'var' and multiple functions are provided +in 'fun', the parameters provided through \dots will be sent to all the +plot functions, as common parameters. To specify concrete arguments for +each of the plot functions see parameter 'special_args'.} + \item{special_args}{List of sub-lists, each sub-list having specific extra arguments for each of the plot functions provided in 'fun'. If you want to fix a different value for each plot in the layout you can do so by @@ -164,12 +202,6 @@ the layout and a 'fileout' has been specified. This is useful to avoid closing the device when saving the layout into a file and willing to add extra elements or figures. Takes TRUE by default. Disregarded if no 'fileout' has been specified.} - -\item{\dots}{Parameters to be sent to the plotting function 'fun'. If -multiple arrays are provided in 'var' and multiple functions are provided -in 'fun', the parameters provided through \dots will be sent to all the -plot functions, as common parameters. To specify concrete arguments for -each of the plot functions see parameter 'special_args'.} } \value{ \item{brks}{ @@ -244,4 +276,3 @@ PlotLayout(PlotEquiMap, c('lat', 'lon'), sampleData$mod[1, , 1, 1, , ], titles = paste('Member', 1:15)) } - diff --git a/man/PlotMatrix.Rd b/man/PlotMatrix.Rd index 24f046d..5275df0 100644 --- a/man/PlotMatrix.Rd +++ b/man/PlotMatrix.Rd @@ -4,12 +4,28 @@ \alias{PlotMatrix} \title{Function to convert any numerical table to a grid of coloured squares.} \usage{ -PlotMatrix(var, brks = NULL, cols = NULL, toptitle = NULL, - title.color = "royalblue4", xtitle = NULL, ytitle = NULL, - xlabels = NULL, xvert = FALSE, ylabels = NULL, line = 3, - figure.width = 1, legend = TRUE, legend.width = 0.15, - xlab_dist = NULL, ylab_dist = NULL, fileout = NULL, size_units = "px", - res = 100, ...) +PlotMatrix( + var, + brks = NULL, + cols = NULL, + toptitle = NULL, + title.color = "royalblue4", + xtitle = NULL, + ytitle = NULL, + xlabels = NULL, + xvert = FALSE, + ylabels = NULL, + line = 3, + figure.width = 1, + legend = TRUE, + legend.width = 0.15, + xlab_dist = NULL, + ylab_dist = NULL, + fileout = NULL, + size_units = "px", + res = 100, + ... +) } \arguments{ \item{var}{A numerical matrix containing the values to be displayed in a @@ -93,4 +109,3 @@ PlotMatrix(var = matrix(rnorm(n = 120, mean = 0.3), 10, 12), xlabels = c("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")) } - diff --git a/man/PlotSection.Rd b/man/PlotSection.Rd index 413ef63..1627339 100644 --- a/man/PlotSection.Rd +++ b/man/PlotSection.Rd @@ -4,10 +4,26 @@ \alias{PlotSection} \title{Plots A Vertical Section} \usage{ -PlotSection(var, horiz, depth, toptitle = "", sizetit = 1, units = "", - brks = NULL, cols = NULL, axelab = TRUE, intydep = 200, - intxhoriz = 20, drawleg = TRUE, fileout = NULL, width = 8, - height = 5, size_units = "in", res = 100, ...) +PlotSection( + var, + horiz, + depth, + toptitle = "", + sizetit = 1, + units = "", + brks = NULL, + cols = NULL, + axelab = TRUE, + intydep = 200, + intxhoriz = 20, + drawleg = TRUE, + fileout = NULL, + width = 8, + height = 5, + size_units = "in", + res = 100, + ... +) } \arguments{ \item{var}{Matrix to plot with (longitude/latitude, depth) dimensions.} @@ -69,4 +85,3 @@ sampleData <- s2dv::sampleDepthData PlotSection(sampleData$mod[1, 1, 1, 1, , ], sampleData$lat, sampleData$depth, toptitle = 'temperature 1995-11 member 0') } - diff --git a/man/PlotStereoMap.Rd b/man/PlotStereoMap.Rd index 4b910a9..95c2f71 100644 --- a/man/PlotStereoMap.Rd +++ b/man/PlotStereoMap.Rd @@ -4,19 +4,53 @@ \alias{PlotStereoMap} \title{Maps A Two-Dimensional Variable On A Polar Stereographic Projection} \usage{ -PlotStereoMap(var, lon, lat, latlims = c(60, 90), toptitle = NULL, - sizetit = NULL, units = NULL, brks = NULL, cols = NULL, - bar_limits = NULL, triangle_ends = NULL, col_inf = NULL, - col_sup = NULL, colNA = NULL, color_fun = clim.palette(), - filled.continents = FALSE, coast_color = NULL, coast_width = 1, - dots = NULL, dot_symbol = 4, dot_size = 0.8, intlat = 10, - drawleg = TRUE, subsampleg = NULL, bar_extra_labels = NULL, - draw_bar_ticks = TRUE, draw_separators = FALSE, triangle_ends_scale = 1, - bar_label_digits = 4, bar_label_scale = 1, units_scale = 1, - bar_tick_scale = 1, bar_extra_margin = rep(0, 4), boxlim = NULL, - boxcol = "purple2", boxlwd = 5, margin_scale = rep(1, 4), - title_scale = 1, numbfig = NULL, fileout = NULL, width = 6, - height = 5, size_units = "in", res = 100, ...) +PlotStereoMap( + var, + lon, + lat, + latlims = c(60, 90), + toptitle = NULL, + sizetit = NULL, + units = NULL, + brks = NULL, + cols = NULL, + bar_limits = NULL, + triangle_ends = NULL, + col_inf = NULL, + col_sup = NULL, + colNA = NULL, + color_fun = clim.palette(), + filled.continents = FALSE, + coast_color = NULL, + coast_width = 1, + dots = NULL, + dot_symbol = 4, + dot_size = 0.8, + intlat = 10, + drawleg = TRUE, + subsampleg = NULL, + bar_extra_labels = NULL, + draw_bar_ticks = TRUE, + draw_separators = FALSE, + triangle_ends_scale = 1, + bar_label_digits = 4, + bar_label_scale = 1, + units_scale = 1, + bar_tick_scale = 1, + bar_extra_margin = rep(0, 4), + boxlim = NULL, + boxcol = "purple2", + boxlwd = 5, + margin_scale = rep(1, 4), + title_scale = 1, + numbfig = NULL, + fileout = NULL, + width = 6, + height = 5, + size_units = "in", + res = 100, + ... +) } \arguments{ \item{var}{Array with the values at each cell of a grid on a regular @@ -183,4 +217,3 @@ y <- seq(from = -90, to = 90, length.out = 50) PlotStereoMap(data, x, y, latlims = c(60, 90), brks = 50, toptitle = "This is the title") } - diff --git a/man/RMS.Rd b/man/RMS.Rd index 7bd33b3..4391df4 100644 --- a/man/RMS.Rd +++ b/man/RMS.Rd @@ -4,8 +4,17 @@ \alias{RMS} \title{Compute root mean square error} \usage{ -RMS(exp, obs, time_dim = "sdate", dat_dim = "dataset", comp_dim = NULL, - limits = NULL, conf = TRUE, conf.lev = 0.95, ncores = NULL) +RMS( + exp, + obs, + time_dim = "sdate", + dat_dim = "dataset", + comp_dim = NULL, + limits = NULL, + conf = TRUE, + conf.lev = 0.95, + ncores = NULL +) } \arguments{ \item{exp}{A named numeric array of experimental data, with at least two @@ -79,4 +88,3 @@ The confidence interval is computed by the chi2 distribution.\cr # Renew example when Ano and Smoothing are ready } - diff --git a/man/RMSSS.Rd b/man/RMSSS.Rd index 1b8274f..9ebcf65 100644 --- a/man/RMSSS.Rd +++ b/man/RMSSS.Rd @@ -4,8 +4,14 @@ \alias{RMSSS} \title{Compute root mean square error skill score} \usage{ -RMSSS(exp, obs, time_dim = "sdate", dat_dim = "dataset", pval = TRUE, - ncores = NULL) +RMSSS( + exp, + obs, + time_dim = "sdate", + dat_dim = "dataset", + pval = TRUE, + ncores = NULL +) } \arguments{ \item{exp}{A named numeric array of experimental data which contains at least @@ -66,4 +72,3 @@ obs <- array(rnorm(15), dim = c(time = 3, memb = 5, dataset = 1)) res <- RMSSS(exp, obs, time_dim = 'time') } - diff --git a/man/RandomWalkTest.Rd b/man/RandomWalkTest.Rd index 33b226f..1110648 100644 --- a/man/RandomWalkTest.Rd +++ b/man/RandomWalkTest.Rd @@ -49,4 +49,3 @@ skill_B <- abs(fcst_B - reference) RandomWalkTest(skill_A = skill_A, skill_B = skill_B, time_dim = 'sdate', ncores = 1) } - diff --git a/man/Regression.Rd b/man/Regression.Rd index 4faafc1..8e27295 100644 --- a/man/Regression.Rd +++ b/man/Regression.Rd @@ -4,8 +4,17 @@ \alias{Regression} \title{Compute the regression of an array on another along one dimension.} \usage{ -Regression(datay, datax, reg_dim = "sdate", formula = y ~ x, pval = TRUE, - conf = TRUE, conf.lev = 0.95, na.action = na.omit, ncores = NULL) +Regression( + datay, + datax, + reg_dim = "sdate", + formula = y ~ x, + pval = TRUE, + conf = TRUE, + conf.lev = 0.95, + na.action = na.omit, + ncores = NULL +) } \arguments{ \item{datay}{An numeric array as predictand including the dimension along @@ -92,4 +101,3 @@ res1 <- Regression(datay, datax, formula = y~poly(x, 2, raw = TRUE)) res2 <- Regression(datay, datax, conf.lev = 0.9) } - diff --git a/man/Reorder.Rd b/man/Reorder.Rd index 0afa07e..8748aaf 100644 --- a/man/Reorder.Rd +++ b/man/Reorder.Rd @@ -26,4 +26,3 @@ Reorder the dimension order of a multi-dimensional array dat2 <- array(c(1:10), dim = c(2, 1, 5)) print(dim(Reorder(dat2, c(2, 1, 3)))) } - diff --git a/man/SPOD.Rd b/man/SPOD.Rd index cbbbf1a..5a20a3f 100644 --- a/man/SPOD.Rd +++ b/man/SPOD.Rd @@ -4,10 +4,22 @@ \alias{SPOD} \title{Compute the South Pacific Ocean Dipole (SPOD) index} \usage{ -SPOD(data, data_lats, data_lons, type, lat_dim = "lat", lon_dim = "lon", - mask = NULL, monini = 11, fmonth_dim = "fmonth", sdate_dim = "sdate", - indices_for_clim = NULL, year_dim = "year", month_dim = "month", - member_dim = "member") +SPOD( + data, + data_lats, + data_lons, + type, + lat_dim = "lat", + lon_dim = "lon", + mask = NULL, + monini = 11, + fmonth_dim = "fmonth", + sdate_dim = "sdate", + indices_for_clim = NULL, + year_dim = "year", + month_dim = "month", + member_dim = "member" +) } \arguments{ \item{data}{A numerical array to be used for the index computation with the @@ -104,4 +116,3 @@ lon <- seq(0, 360, 10) index_dcpp <- SPOD(data = dcpp, data_lats = lat, data_lons = lon, type = 'dcpp', monini = 1) } - diff --git a/man/Season.Rd b/man/Season.Rd index cb10dee..3c1e3ff 100644 --- a/man/Season.Rd +++ b/man/Season.Rd @@ -4,8 +4,16 @@ \alias{Season} \title{Compute seasonal mean} \usage{ -Season(data, time_dim = "ftime", monini, moninf, monsup, method = mean, - na.rm = TRUE, ncores = NULL) +Season( + data, + time_dim = "ftime", + monini, + moninf, + monsup, + method = mean, + na.rm = TRUE, + ncores = NULL +) } \arguments{ \item{data}{A named numeric array with at least one dimension 'time_dim'.} @@ -53,4 +61,3 @@ dat2[na] <- NA res <- Season(data = dat2, monini = 3, moninf = 1, monsup = 2) res <- Season(data = dat2, monini = 3, moninf = 1, monsup = 2, na.rm = FALSE) } - diff --git a/man/Smoothing.Rd b/man/Smoothing.Rd index ba62ca1..8d4a558 100644 --- a/man/Smoothing.Rd +++ b/man/Smoothing.Rd @@ -43,4 +43,3 @@ PlotAno(smooth_ano_exp, smooth_ano_obs, startDates, fileout = "tos_smoothed_ano.png") } } - diff --git a/man/TPI.Rd b/man/TPI.Rd index 6968f22..fdbc2b8 100644 --- a/man/TPI.Rd +++ b/man/TPI.Rd @@ -4,10 +4,22 @@ \alias{TPI} \title{Compute the Tripole Index (TPI) for the Interdecadal Pacific Oscillation (IPO)} \usage{ -TPI(data, data_lats, data_lons, type, lat_dim = "lat", lon_dim = "lon", - mask = NULL, monini = 11, fmonth_dim = "fmonth", sdate_dim = "sdate", - indices_for_clim = NULL, year_dim = "year", month_dim = "month", - member_dim = "member") +TPI( + data, + data_lats, + data_lons, + type, + lat_dim = "lat", + lon_dim = "lon", + mask = NULL, + monini = 11, + fmonth_dim = "fmonth", + sdate_dim = "sdate", + indices_for_clim = NULL, + year_dim = "year", + month_dim = "month", + member_dim = "member" +) } \arguments{ \item{data}{A numerical array to be used for the index computation with the @@ -103,4 +115,3 @@ lon = seq(0, 360, 10) index_dcpp = TPI(data = dcpp, data_lats = lat, data_lons = lon, type = 'dcpp', monini = 1) } - diff --git a/man/ToyModel.Rd b/man/ToyModel.Rd index 379ed3b..ee7a98e 100644 --- a/man/ToyModel.Rd +++ b/man/ToyModel.Rd @@ -7,8 +7,18 @@ components of a forecast: (1) predictabiltiy (2) forecast error (3) non-stationarity and (4) ensemble generation. The forecast can be computed for real observations or observations generated artifically.} \usage{ -ToyModel(alpha = 0.1, beta = 0.4, gamma = 1, sig = 1, trend = 0, - nstartd = 30, nleadt = 4, nmemb = 10, obsini = NULL, fxerr = NULL) +ToyModel( + alpha = 0.1, + beta = 0.4, + gamma = 1, + sig = 1, + trend = 0, + nstartd = 30, + nleadt = 4, + nmemb = 10, + obsini = NULL, + fxerr = NULL +) } \arguments{ \item{alpha}{Predicabiltiy of the forecast on the observed residuals @@ -120,4 +130,3 @@ toyforecast <- ToyModel(alpha = a, beta = b, gamma = g, nmemb = nm, # } } - diff --git a/man/Trend.Rd b/man/Trend.Rd index a641041..d283ee6 100644 --- a/man/Trend.Rd +++ b/man/Trend.Rd @@ -4,8 +4,16 @@ \alias{Trend} \title{Compute the trend} \usage{ -Trend(data, time_dim = "ftime", interval = 1, polydeg = 1, conf = TRUE, - conf.lev = 0.95, pval = TRUE, ncores = NULL) +Trend( + data, + time_dim = "ftime", + interval = 1, + polydeg = 1, + conf = TRUE, + conf.lev = 0.95, + pval = TRUE, + ncores = NULL +) } \arguments{ \item{data}{An numeric array including the dimension along which the trend @@ -80,4 +88,3 @@ months_between_startdates <- 60 trend <- Trend(sampleData$obs, polydeg = 2, interval = months_between_startdates) } - diff --git a/man/clim.palette.Rd b/man/clim.palette.Rd index d912f47..5d17947 100644 --- a/man/clim.palette.Rd +++ b/man/clim.palette.Rd @@ -1,8 +1,8 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/clim.palette.R \name{clim.palette} -\alias{clim.colors} \alias{clim.palette} +\alias{clim.colors} \title{Generate Climate Color Palettes} \usage{ clim.palette(palette = "bluered") @@ -30,4 +30,3 @@ cols <- clim.colors(20) ColorBar(lims, cols) } - diff --git a/man/s2dv-package.Rd b/man/s2dv-package.Rd index cb52214..043b081 100644 --- a/man/s2dv-package.Rd +++ b/man/s2dv-package.Rd @@ -4,20 +4,45 @@ \name{s2dv-package} \alias{s2dv} \alias{s2dv-package} -\title{A Set of Common Tools for Seasonal to Decadal Verification} +\title{s2dv: A Set of Common Tools for Seasonal to Decadal Verification} \description{ -The advanced version of package 's2dverification'. It is -intended for 'seasonal to decadal' (s2d) climate forecast verification, but -it can also be used in other kinds of forecasts or general climate analysis. -This package is specially designed for the comparison between the experimental -and observational datasets. The functionality of the included functions covers -from data retrieval, data post-processing, skill scores against observation, -to visualization. Compared to 's2dverification', 's2dv' is more compatible -with the package 'startR', able to use multiple cores for computation and -handle multi-dimensional arrays with a higher flexibility. +The advanced version of package 's2dverification'. It is + intended for 'seasonal to decadal' (s2d) climate forecast verification, but + it can also be used in other kinds of forecasts or general climate analysis. + This package is specially designed for the comparison between the experimental + and observational datasets. The functionality of the included functions covers + from data retrieval, data post-processing, skill scores against observation, + to visualization. Compared to 's2dverification', 's2dv' is more compatible + with the package 'startR', able to use multiple cores for computation and + handle multi-dimensional arrays with a higher flexibility. } \references{ \url{https://earth.bsc.es/gitlab/es/s2dv/} } -\keyword{internal} +\seealso{ +Useful links: +\itemize{ + \item \url{https://earth.bsc.es/gitlab/es/s2dv/} + \item Report bugs at \url{https://earth.bsc.es/gitlab/es/s2dv/-/issues} +} + +} +\author{ +\strong{Maintainer}: An-Chi Ho \email{an.ho@bsc.es} + +Authors: +\itemize{ + \item BSC-CNS [copyright holder] + \item Nuria Perez-Zanon \email{nuria.perez@bsc.es} +} + +Other contributors: +\itemize{ + \item Roberto Bilbao \email{roberto.bilbao@bsc.es} [contributor] + \item Carlos Delgado \email{carlos.delgado@bsc.es} [contributor] + \item Andrea Manrique \email{andrea.manrique@bsc.es} [contributor] + \item Deborah Verfaillie \email{deborah.verfaillie@bsc.es} [contributor] +} +} +\keyword{internal} diff --git a/man/sampleDepthData.Rd b/man/sampleDepthData.Rd index 869af86..77e4a7a 100644 --- a/man/sampleDepthData.Rd +++ b/man/sampleDepthData.Rd @@ -28,4 +28,3 @@ variable 'tos', i.e. sea surface temperature, from the decadal climate prediction experiment run at IC3 in the context of the CMIP5 project.\cr Its name within IC3 local database is 'i00k'. } - diff --git a/man/sampleMap.Rd b/man/sampleMap.Rd index 651d185..eaf8aa5 100644 --- a/man/sampleMap.Rd +++ b/man/sampleMap.Rd @@ -43,4 +43,3 @@ sampleData <- Load('tos', list(exp), list(obs), startDates, } Check the documentation on 'Load()' in the package 's2dv' for more information. } - diff --git a/man/sampleTimeSeries.Rd b/man/sampleTimeSeries.Rd index 280277e..05a8e79 100644 --- a/man/sampleTimeSeries.Rd +++ b/man/sampleTimeSeries.Rd @@ -47,4 +47,3 @@ sampleData <- Load('tos', list(exp), list(obs), startDates, } Check the documentation on 'Load()' in the package 's2dv' for more information. } - -- GitLab From 24e901ca068e95527248456b5d9d96860fc2d6e6 Mon Sep 17 00:00:00 2001 From: aho Date: Wed, 28 Apr 2021 17:17:53 +0200 Subject: [PATCH 4/5] Fix 'thr' when quantile = F --- R/ProbBins.R | 14 ++++++++++---- man/ProbBins.Rd | 5 +++-- tests/testthat/test-ProbBins.R | 15 ++++++++++++++- 3 files changed, 27 insertions(+), 7 deletions(-) diff --git a/R/ProbBins.R b/R/ProbBins.R index 0bb8876..c76ad43 100644 --- a/R/ProbBins.R +++ b/R/ProbBins.R @@ -7,8 +7,9 @@ #' #'@param data An numeric array of anomalies with the dimensions 'time_dim' and #' 'memb_dim' at least. It can be generated by \code{Ano()}. -#'@param thr A numeric vector within range [0, 1] used as the thresholds to bin -#' the anomalies. +#'@param thr A numeric vector used as the quantiles (if 'quantile' is TRUE) or +#' thresholds (if 'quantile' is FALSE) to bin the anomalies. If it is quantile, +#' it must be within [0, 1]. #'@param fcyr A numeric vector of the indices of the forecast years (i.e., #' time_dim) to compute the probabilistic bins for, or 'all' to compute the #' bins for all the years. E.g., c(1:5), c(1, 4), 4, or 'all'. The default @@ -74,10 +75,15 @@ ProbBins <- function(data, thr, fcyr = 'all', time_dim = 'sdate', memb_dim = 'me stop("Parameter 'data' must have dimension names.") } ## thr + if (is.null(thr)) { + stop("Parameter 'thr' cannot be NULL.") + } if (!is.numeric(thr) | !is.vector(thr)) { stop("Parameter 'thr' must be a numeric vector.") - } else if (max(thr) > 1 | min(thr) < 0) { - stop("Parameter 'thr' must be within the range [0, 1].") + } else if (quantile) { + if (!all(thr <= 1 & thr >= 0)) { + stop("Parameter 'thr' must be within the range [0, 1] if 'quantile' is TRUE.") + } } ## time_dim if (!is.character(time_dim) | length(time_dim) > 1) { diff --git a/man/ProbBins.Rd b/man/ProbBins.Rd index 9e46690..26b88b8 100644 --- a/man/ProbBins.Rd +++ b/man/ProbBins.Rd @@ -19,8 +19,9 @@ ProbBins( \item{data}{An numeric array of anomalies with the dimensions 'time_dim' and 'memb_dim' at least. It can be generated by \code{Ano()}.} -\item{thr}{A numeric vector within range [0, 1] used as the thresholds to bin -the anomalies.} +\item{thr}{A numeric vector used as the quantiles (if 'quantile' is TRUE) or +thresholds (if 'quantile' is FALSE) to bin the anomalies. If it is quantile, +it must be within [0, 1].} \item{fcyr}{A numeric vector of the indices of the forecast years (i.e., time_dim) to compute the probabilistic bins for, or 'all' to compute the diff --git a/tests/testthat/test-ProbBins.R b/tests/testthat/test-ProbBins.R index 83e4f3b..4b3d0ec 100644 --- a/tests/testthat/test-ProbBins.R +++ b/tests/testthat/test-ProbBins.R @@ -21,13 +21,17 @@ test_that("1. Input checks", { "Parameter 'data' must have dimension names." ) # thr + expect_error( + ProbBins(dat1, thr = c()), + "Parameter 'thr' cannot be NULL." + ) expect_error( ProbBins(dat1, thr = TRUE), "Parameter 'thr' must be a numeric vector." ) expect_error( ProbBins(dat1, thr = 1:10), - "Parameter 'thr' must be within the range \\[0, 1\\]." + "Parameter 'thr' must be within the range \\[0, 1\\] if 'quantile' is TRUE." ) # time_dim expect_error( @@ -155,5 +159,14 @@ expect_equal( which(ProbBins(dat1, thr = c(1/3, 2/3), quantile = FALSE) == 1), c(1, 6, 8, 10, 13, 16, 21, 24, 25, 28, 32, 35, 37, 40, 45, 48, 49, 52, 56, 58, 63, 66, 69, 70) ) +expect_equal( +length(which(ProbBins(dat1, thr = c(1:3), quantile = FALSE) == 0)), +72 +) +expect_equal( +length(which(ProbBins(dat1, thr = c(1:3), quantile = FALSE) == 1)), +24 +) + }) -- GitLab From 526aa5d92d1fa3f749de51b8a4473be5a17bb014 Mon Sep 17 00:00:00 2001 From: aho Date: Thu, 6 May 2021 17:25:37 +0200 Subject: [PATCH 5/5] Revise documentation of @return --- R/ProbBins.R | 12 ++++++------ man/ProbBins.Rd | 12 ++++++------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/R/ProbBins.R b/R/ProbBins.R index c76ad43..327ceb3 100644 --- a/R/ProbBins.R +++ b/R/ProbBins.R @@ -32,12 +32,12 @@ #'@param ncores An integer indicating the number of cores to use for parallel #' computation. The default value is NULL. #' -#'@return Array with probabilistic information and dimensions:\cr -#' c(length('thr') + 1, length(fcyr), nmemb/nparam, nmod/nexp/nobs, -#' nltime, nlat, nlon)\cr -#' The values along the first dimension take values 0 or 1 depending on which -#' of the 'thr'+1 cathegories the forecast/observation at the corresponding -#' grid point, time step, member and starting date belongs to. +#'@return A numeric array of probabilistic information with dimensions:\cr +#' c(bin = length of 'thr' + 1, time_dim = length of 'fcyr', memb_dim, the +#' rest of dimensions of 'data')\cr +#' The values along the 'bin' dimension take values 0 or 1 depending on which +#' of the 'thr' + 1 cathegories the forecast or observation at the corresponding +#' grid point, time step, member and start date belongs to. #' #'@examples #'\dontshow{ diff --git a/man/ProbBins.Rd b/man/ProbBins.Rd index 26b88b8..cfd7aff 100644 --- a/man/ProbBins.Rd +++ b/man/ProbBins.Rd @@ -51,12 +51,12 @@ The default value is "Full period".} computation. The default value is NULL.} } \value{ -Array with probabilistic information and dimensions:\cr - c(length('thr') + 1, length(fcyr), nmemb/nparam, nmod/nexp/nobs, - nltime, nlat, nlon)\cr - The values along the first dimension take values 0 or 1 depending on which - of the 'thr'+1 cathegories the forecast/observation at the corresponding - grid point, time step, member and starting date belongs to. +A numeric array of probabilistic information with dimensions:\cr + c(bin = length of 'thr' + 1, time_dim = length of 'fcyr', memb_dim, the + rest of dimensions of 'data')\cr + The values along the 'bin' dimension take values 0 or 1 depending on which + of the 'thr' + 1 cathegories the forecast or observation at the corresponding + grid point, time step, member and start date belongs to. } \description{ Compute probabilistic bins of a set of forecast years ('fcyr') relative to -- GitLab