diff --git a/NAMESPACE b/NAMESPACE index cb900eef1b4c3d85ed441b02f9d0f0b1ca7f36f9..5884b2e411691d6b4ac1984dc618f7349ad10e0e 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,10 +1,12 @@ # Generated by roxygen2: do not edit by hand export(AdamontAnalog) +export(AdamontQQCorr) export(Analogs) export(BEI_PDFBest) export(BEI_Weights) export(BiasCorrection) +export(CST_AdamontAnalog) export(CST_Analogs) export(CST_AnalogsPredictors) export(CST_Anomaly) diff --git a/R/AnalogsPred_train.R b/R/AnalogsPred_train.R index c68c48b05cd5991de93ff5f1282fa761148693a1..468c74fa1b97c3b13b304119a990a89dc7bf17d5 100644 --- a/R/AnalogsPred_train.R +++ b/R/AnalogsPred_train.R @@ -5,235 +5,250 @@ #'@author Marta Dominguez Alonso - AEMET, \email{mdomingueza@aemet.es} #'@author Nuria Perez-Zanon - BSC, \email{nuria.perez@bsc.es} #' -#'@description This function caracterizes the synoptic situations in a past period based on -#' low resolution reanalysis data (e.g, ERAInterim 1.5º x 1.5º) and an observational high -#' resolution (HR) dataset (AEMET 5 km gridded daily precipitation and maximum and -#' minimum temperature) (Peral et al., 2017)). -#' The method uses three domains: -#' - peninsular Spain and Balearic Islands domain (5 km resolution): HR domain -#' - synoptic domain (low resolution): it should be centered over Iberian Peninsula and -#' cover enough extension to detect as much synoptic situations as possible. -#' - extended domain (low resolution): it is an extension of the synoptic -#' domain. It is used for 'slp_ext' parameter (see 'slp_lon' and 'slp_lat' below). -#'@param pred List of matrix reanalysis data in a synoptic domain. The list -#' has to contain reanalysis atmospheric variables (instantaneous 12h data) -#' that must be indentify by parenthesis name. -#' For precipitation: -#' - u component of wind at 500 hPa (u500) in m/s -#' - v component of wind at 500 hPa (v500) in m/s -#' - temperature at 500 hPa (t500) in K -#' - temperature at 850 hPa (t850) in K -#' - temperature at 1000 hPa (t1000) in K -#' - geopotential height at 500 hPa (z500) in m -#' - geopotential height at 1000 hPa (z1000) in m -#' - sea level pressure (slp) in hPa -#' - specific humidity at 700 hPa (q700) in g/kg -#' For maximum and minimum temperature: -#' - temperature at 1000 hPa (t1000) in K -#' - sea level pressure (slp) in hPa -#' All matrix must have [time,gridpoint] dimensions. -#' (time = number of training days, gridpoint = number of synoptic gridpoints). +#'@description This function caracterizes the synoptic situations in a past +#'period based on low resolution reanalysis data (e.g, ERAInterim 1.5º x 1.5º) +#'and an observational high resolution (HR) dataset (AEMET 5 km gridded daily +#'precipitation and maximum and minimum temperature) (Peral et al., 2017)). +#'The method uses three domains: +#'\itemize{ +#' \item{peninsular Spain and Balearic Islands domain (5 km resolution): HR domain} +#' \item{synoptic domain (low resolution): it should be centered over Iberian +#' Peninsula and cover enough extension to detect as much synoptic +#' situations as possible.} +#' \item{extended domain (low resolution): it is an extension of the synoptic +#' domain. It is used for 'slp_ext' parameter (see 'slp_lon' and 'slp_lat' +#' below).} +#'} +#'@param pred List of matrix reanalysis data in a synoptic domain. The list has +#' to contain reanalysis atmospheric variables (instantaneous 12h data) that +#' must be indentify by parenthesis name. For precipitation: +#' \itemize{ +#' \item{u component of wind at 500 hPa (u500) in m/s} +#' \item{v component of wind at 500 hPa (v500) in m/s} +#' \item{temperature at 500 hPa (t500) in K} +#' \item{temperature at 850 hPa (t850) in K} +#' \item{temperature at 1000 hPa (t1000) in K} +#' \item{geopotential height at 500 hPa (z500) in m} +#' \item{geopotential height at 1000 hPa (z1000) in m} +#' \item{sea level pressure (slp) in hPa} +#' \item{specific humidity at 700 hPa (q700) in g/kg} +#' } +#' For maximum and minimum temperature: +#' \itemize{ +#' \item{temperature at 1000 hPa (t1000) in K} +#' \item{sea level pressure (slp) in hPa} +#' } +#' All matrix must have [time,gridpoint] dimensions. +#' (time = number of training days, gridpoint = number of synoptic gridpoints). #'@param slp_ext Matrix with atmospheric reanalysis sea level pressure -#' (instantaneous 12h data)(hPa). It has the same resolution as 'pred' parameter -#' but with an extended domain. This domain contains extra degrees (most in the -#' north and west part) compare to synoptic domain. The matrix must have -#' [time,gridpoint] dimensions. -#' (time = number of training days, gridpoint = number of extended gridpoints). +#' (instantaneous 12h data)(hPa). It has the same resolution as 'pred' parameter +#' but with an extended domain. This domain contains extra degrees (most in the +#' north and west part) compare to synoptic domain. The matrix must have +#' [time,gridpoint] dimensions. (time = number of training days, +#' gridpoint = number of extended gridpoints). #'@param lon Vector of the synoptic longitude (from (-180º) to 180º), -#' The vector must go from west to east. -#'@param lat Vector of the synoptic latitude. The vector must go from north to south. -#'@param slp_lon Vector of the extended longitude (from (-180º) to 180º) -#' The vector must go from west to east. -#'@param slp_lat Vector of the extended latitude. The vector must go from north to south. +#' The vector must go from west to east. +#'@param lat Vector of the synoptic latitude. The vector must go from north to +#' south. +#'@param slp_lon Vector of the extended longitude (from (-180º) to 180º). +#' The vector must go from west to east. +#'@param slp_lat Vector of the extended latitude. The vector must go from north +#' to south. #'@param var Variable name to downscale. There are two options: 'prec' for -#' precipitation and 'temp' for maximum and minimum temperature. +#' precipitation and 'temp' for maximum and minimum temperature. #'@param HR_path Local path of HR observational files (maestro and pcp/tmx-tmn). -#' For precipitation can be downloaded from http://www.aemet.es/documentos/es/serviciosclimaticos/cambio_climat/datos_diarios/dato_observacional/rejilla_5km/v2/Serie_AEMET_v2_pcp_1951a202006_txt.tar.gz -#' For maximum and minimum temperature can be downloaded from http://www.aemet.es/documentos/es/serviciosclimaticos/cambio_climat/datos_diarios/dato_observacional/rejilla_5km/temperatura/v1/tmax/Serie_AEMET_v1_tmax_1951a202006_txt.tar.gz and http://www.aemet.es/documentos/es/serviciosclimaticos/cambio_climat/datos_diarios/dato_observacional/rejilla_5km/temperatura/v1/tmin/Serie_AEMET_v1_tmin_1951a202006_txt.tar.gz respetively. -#' Maestro file (maestro_red_hr_SPAIN.txt) has gridpoint (nptos), longitude (lon), latitude (lat) and -#' altitude (alt) in columns (vector structure). -#' Data file (pcp/tmx/tmn_red_SPAIN_1951-201903.txt) includes 5km resolution spanish daily data -#' (precipitation or maximum and minimum temperature from january 1951 to june 2020. See README -#' file for more information. -#' IMPORTANT!: HR observational period must be the same as for reanalysis variables. -#' It is assumed that the training period is smaller than the HR original one (1951-2020), so it is -#' needed to make a new ascii file with the new period and the same structure as original, -#' specifying the training dates ('tdates' parameter) in the name -#' (e.g. 'pcp_red_SPAIN_19810101-19961231.txt' for '19810101-19961231' period). -#'@param tdates Training period dates in format YYYYMMDD(start)-YYYYMMDD(end) (e.g. 19810101-19961231). -#'@return matrix list (e.g. restrain) as a result of characterize the past synoptic -#' situations and the significant predictors needed to downscale seasonal forecast variables. -#' For precipitation the output includes: -#' um: u component of geostrophic wind in all period (numeric matrix with [time,gridpoint] dimensions) -#' vm: v component of geostrophic wind in all period (numeric matrix with [time,gridpoint] dimensions) -#' nger: number of synoptic situations (integer) -#' gu92: u component of geostrophic wind for each synoptic situation (numeric matrix with -#' [nger,gridpoint] dimensions) -#' gv92: v component of geostrophic wind for each synoptic situation (numeric matrix with -#' [nger,gridpoint] dimensions) -#' gu52: u component of wind at 500 hPa for each synotic situation (numeric matrix with -#' [nger,gridpoint] dimensions) -#' gv52: v component of wind at 500 hPa for each synotic situation (numeric matrix with -#' [nger,gridpoint] dimensions) -#' neni: number of reference centers where predictors are calculated (integer) -#' vdmin: minimum distances between each HR gridpoint and the four nearest synoptic -#' gridpoints (numeric matrix with [nptos,4] dimensions) (nptos = number of HR gridpoints) -#' vref: four nearest synoptic gridpoints to each HR gridpoint (integer matrix with -#' [nptos,4] dimensions) -#' ccm: multiple correlation coeficients (numeric matrix with [nger,nptos] dimensions) -#' indices: -#' - lab_pred: numeric labels of selected predictors (integer matrix -#' with [nger,nptos,11,1] dimensions) -#' - cor_pred: partial correlation of selected predictors (numeric matrix with -#' [nger,nptos,11,2] dimensions) -#' For maximum and minimum temperature the output includes: -#' um: u component of geostrophic wind in all training period (numeric matrix with [time,gridpoint] dimensions) -#' vm: v component of geostrophic wind in all training period (numeric matrix with [time,gridpoint] dimensions) -#' insol: insolation in all training period (numeric vector with [time] dimension) -#' neni: number of reference centers where predictors are calculated (integer) -#' vdmin: minimum distances between each HR gridpoint and the four nearest synoptic -#' gridpoints (numeric matrix with [nptos,4] dimensions) (nptos = number of HR gridpoints) -#' vref: four nearest synoptic gridpoints to each HR gridpoint (integer matrix with -#' [nptos,4] dimensions) -#' -#' The output can directly use as argument to 'CST_AnalogsPredictors' function -#' (e.g. resdowns <- CST_AnalogsPredictors(...,restrain)) -#' +#' For precipitation and temperature can be downloaded from the following link: +#' \url{https://www.aemet.es/en/serviciosclimaticos/cambio_climat/datos_diarios?w=2} +#' respetively. Maestro file (maestro_red_hr_SPAIN.txt) has gridpoint (nptos), +#' longitude (lon), latitude (lat) and altitude (alt) in columns (vector +#' structure). Data file (pcp/tmx/tmn_red_SPAIN_1951-201903.txt) includes 5km +#' resolution spanish daily data (precipitation or maximum and minimum +#' temperature from january 1951 to june 2020. See README file for more +#' information. IMPORTANT!: HR observational period must be the same as for +#' reanalysis variables. It is assumed that the training period is smaller than +#' the HR original one (1951-2020), so it is needed to make a new ascii file +#' with the new period and the same structure as original, specifying the +#' training dates ('tdates' parameter) in the name (e.g. +#' 'pcp_red_SPAIN_19810101-19961231.txt' for '19810101-19961231' period). +#'@param tdates Training period dates in format YYYYMMDD(start)-YYYYMMDD(end) +#' (e.g. 19810101-19961231). +#'@return A matrix list (e.g. restrain) as a result of characterize the past +#'synoptic situations and the significant predictors needed to downscale +#'seasonal forecast variables. For precipitation the output includes: +#'\itemize{ +#' \item{'um': u component of geostrophic wind in all period (numeric matrix +#' with [time, gridpoint] dimensions).} +#' \item{'vm': v component of geostrophic wind in all period (numeric matrix +#' with [time,gridpoint] dimensions).} +#' \item{'nger': number of synoptic situations (integer).} +#' \item{'gu92': u component of geostrophic wind for each synoptic situation +#' (numeric matrix with [nger,gridpoint] dimensions).} +#' \item{'gv92': v component of geostrophic wind for each synoptic situation +#' (numeric matrix with [nger, gridpoint] dimensions).} +#' \item{'gu52': u component of wind at 500 hPa for each synotic situation +#' (numeric matrix with [nger, gridpoint] dimensions).} +#' \item{'gv52': v component of wind at 500 hPa for each synotic situation +#' (numeric matrix with [nger, gridpoint] dimensions).} +#' \item{'neni': number of reference centers where predictors are calculated +#' (integer).} +#' \item{'vdmin': minimum distances between each HR gridpoint and the four +#' nearest synoptic gridpoints (numeric matrix with [nptos,4] dimensions) +#' (nptos = number of HR gridpoints).} +#' \item{'vref': four nearest synoptic gridpoints to each HR gridpoint (integer +#' matrix with [nptos, 4] dimensions).} +#' \item{'ccm': multiple correlation coeficients (numeric matrix with [nger, nptos] +#' dimensions) indices: +#' \itemize{ +#' \item{'lab_pred': numeric labels of selected predictors (integer matrix +#' with [nger,nptos,11,1] dimensions).} +#' \item{'cor_pred': partial correlation of selected predictors (numeric +#' matrix with [nger,nptos,11,2] dimensions).} +#' } +#' } +#' } +#'For maximum and minimum temperature the output includes: +#'\itemize{ +#' \item{'um': u component of geostrophic wind in all training period (numeric +#' matrix with [time,gridpoint] dimensions).} +#' \item{'vm': v component of geostrophic wind in all training period (numeric +#' matrix with [time,gridpoint] dimensions).} +#' \item{'insol': insolation in all training period (numeric vector with [time] +#' dimension).} +#' \item{'neni': number of reference centers where predictors are calculated +#' (integer).} +#' \item{'vdmin': minimum distances between each HR gridpoint and the four +#' nearest synoptic gridpoints (numeric matrix with [nptos,4] dimensions) +#' (nptos = number of HR gridpoints).} +#' \item{'vref': four nearest synoptic gridpoints to each HR gridpoint (integer +#' matrix with [nptos,4] dimensions).} +#'} +#'The output can directly use as argument to 'CST_AnalogsPredictors' function +#'(e.g. resdowns <- CST_AnalogsPredictors(...,restrain)). #'@importFrom utils read.table -#' #'@useDynLib CSTools -#' #'@export +training_analogs <- function(pred, slp_ext, lon, lat, slp_lon, slp_lat, var, + HR_path, tdates) { -training_analogs <- function(pred, - slp_ext, - lon, - lat, - slp_lon, - slp_lat, - var, - HR_path, - tdates) { - -if (!is.list(pred)) { + if (!is.list(pred)) { stop("Parameter 'pred' must be a list of 'matrix' objects") } -if (!(all(sapply(pred, inherits, 'matrix')))) { + if (!(all(sapply(pred, inherits, 'matrix')))) { stop("Elements of the list in parameter 'pred' must be of the class ", "'matrix'.") } -if (var == "prec") { - if (length(pred) != 9) { - stop("Parameter 'pred' must be a length of 9.") - } else { - if (is.null(names(dim(pred[[1]]))) || - is.null(names(dim(pred[[2]]))) || - is.null(names(dim(pred[[3]]))) || - is.null(names(dim(pred[[4]]))) || - is.null(names(dim(pred[[5]]))) || - is.null(names(dim(pred[[6]]))) || - is.null(names(dim(pred[[7]]))) || - is.null(names(dim(pred[[8]]))) || - is.null(names(dim(pred[[9]])))) { - stop("Parameter 'pred' should have dimmension names.") - } - if (!(any(names(pred) %in% "u500"))) { - stop("Variable 'u500' in pred parameter is missed.") - } else if (!(any(names(pred) %in% "v500"))) { - stop("Variable 'v500' in pred parameter is missed.") - } else if (!(any(names(pred) %in% "t500"))) { - stop("Variable 't500' in pred parameter is missed.") - } else if (!(any(names(pred) %in% "t850"))) { - stop("Variable 't850' in pred parameter is missed.") - } else if (!(any(names(pred) %in% "t1000"))) { - stop("Variable 't1000' in pred parameter is missed.") - } else if (!(any(names(pred) %in% "z500"))) { - stop("Variable 'z500' in pred parameter is missed.") - } else if (!(any(names(pred) %in% "z1000"))) { - stop("Variable 'z1000' in pred parameter is missed.") - } else if (!(any(names(pred) %in% "slp"))) { - stop("Variable 'slp' in pred parameter is missed.") - } else if (!(any(names(pred) %in% "q700"))) { - stop("Variable 'q700' in pred parameter is missed.") + if (var == "prec") { + if (length(pred) != 9) { + stop("Parameter 'pred' must be a length of 9.") + } else { + if (is.null(names(dim(pred[[1]]))) || + is.null(names(dim(pred[[2]]))) || + is.null(names(dim(pred[[3]]))) || + is.null(names(dim(pred[[4]]))) || + is.null(names(dim(pred[[5]]))) || + is.null(names(dim(pred[[6]]))) || + is.null(names(dim(pred[[7]]))) || + is.null(names(dim(pred[[8]]))) || + is.null(names(dim(pred[[9]])))) { + stop("Parameter 'pred' should have dimmension names.") } - } -} else { - if (length(pred) != 2) { - stop("Parameter 'pred' must be a length of 2.") - } else { - if (is.null(names(dim(pred[[1]]))) || - is.null(names(dim(pred[[2]])))) { - stop("Parameter 'pred' should have dimmension names.") - } - if (!(any(names(pred) %in% "t1000"))) { - stop("Variable 't1000' in pred parameter is missed.") - } else if (!(any(names(pred) %in% "slp"))) { - stop("Variable 'slp' in pred parameter is missed.") - } - } -} + if (!(any(names(pred) %in% "u500"))) { + stop("Variable 'u500' in pred parameter is missed.") + } else if (!(any(names(pred) %in% "v500"))) { + stop("Variable 'v500' in pred parameter is missed.") + } else if (!(any(names(pred) %in% "t500"))) { + stop("Variable 't500' in pred parameter is missed.") + } else if (!(any(names(pred) %in% "t850"))) { + stop("Variable 't850' in pred parameter is missed.") + } else if (!(any(names(pred) %in% "t1000"))) { + stop("Variable 't1000' in pred parameter is missed.") + } else if (!(any(names(pred) %in% "z500"))) { + stop("Variable 'z500' in pred parameter is missed.") + } else if (!(any(names(pred) %in% "z1000"))) { + stop("Variable 'z1000' in pred parameter is missed.") + } else if (!(any(names(pred) %in% "slp"))) { + stop("Variable 'slp' in pred parameter is missed.") + } else if (!(any(names(pred) %in% "q700"))) { + stop("Variable 'q700' in pred parameter is missed.") + } + } + } else { + if (length(pred) != 2) { + stop("Parameter 'pred' must be a length of 2.") + } else { + if (is.null(names(dim(pred[[1]]))) || + is.null(names(dim(pred[[2]])))) { + stop("Parameter 'pred' should have dimmension names.") + } + if (!(any(names(pred) %in% "t1000"))) { + stop("Variable 't1000' in pred parameter is missed.") + } else if (!(any(names(pred) %in% "slp"))) { + stop("Variable 'slp' in pred parameter is missed.") + } + } + } - if (all((sapply(pred,dim))==dim(pred[[1]])) & - all((sapply(pred,function(pred){names(dim(pred))}))==names(dim(pred[[1]])))) { - dim_pred <- dim(pred[[1]]) - if (!(any(names(dim_pred) %in% "time"))) { - stop("Dimension 'time' in pred parameter is missed.") - } - if (!(any(names(dim_pred) %in% "gridpoint"))) { - stop("Dimension 'gridpoint' in pred parameter is missed.") - } - if (names(dim_pred)[1] == "gridpoint") { - pred <- lapply(pred,aperm) - } else { - pred <- pred - } - } else { - stop("All 'pred' variables must have the same dimensions and name dimensions.") - } - -if (!is.vector(lon) || !is.numeric(lon)) { + if (all((sapply(pred,dim)) == dim(pred[[1]])) & + all((sapply(pred, function(pred){names(dim(pred))})) == names(dim(pred[[1]])))) { + dim_pred <- dim(pred[[1]]) + if (!(any(names(dim_pred) %in% "time"))) { + stop("Dimension 'time' in pred parameter is missed.") + } + if (!(any(names(dim_pred) %in% "gridpoint"))) { + stop("Dimension 'gridpoint' in pred parameter is missed.") + } + if (names(dim_pred)[1] == "gridpoint") { + pred <- lapply(pred,aperm) + } else { + pred <- pred + } + } else { + stop("All 'pred' variables must have the same dimensions and name dimensions.") + } + + if (!is.vector(lon) || !is.numeric(lon)) { stop("Parameter 'lon' must be a numeric vector") -} else { + } else { if (is.unsorted(lon)) { - lon <- sort(lon) - warning("'lon' vector has been sorted in increasing order") + lon <- sort(lon) + warning("'lon' vector has been sorted in increasing order") } -} + } -if (!is.vector(lat) || !is.numeric(lat)) { + if (!is.vector(lat) || !is.numeric(lat)) { stop("Parameter 'lat' must be a numeric vector") -} else { + } else { if (!is.unsorted(lat)) { - lat <- sort(lat, decreasing = TRUE) - warning("'lat' vector has been sorted in decreasing order") + lat <- sort(lat, decreasing = TRUE) + warning("'lat' vector has been sorted in decreasing order") } -} + } -if (!is.character(HR_path)) { + if (!is.character(HR_path)) { stop("Parameter 'HR_path' must be a character.") -} else { - if (!dir.exists(HR_path)) { - stop("'HR_path' directory does not exist") - } -} + } else { + if (!dir.exists(HR_path)) { + stop("'HR_path' directory does not exist") + } + } -if (!is.character(tdates)) { - stop("Parameter 'tdates' must be a character.") -} else { - if (nchar(tdates) != "17") { - stop("Parameter 'tdates' must be a string with 17 charecters.") - } else { - dateini <- as.Date(substr(tdates,start=1,stop=8),format="%Y%m%d") - dateend <- as.Date(substr(tdates,start=10,stop=18),format="%Y%m%d") - if (dateend <= dateini) { - stop("Parameter 'tdates' must be at least of one day") - } - } -} + if (!is.character(tdates)) { + stop("Parameter 'tdates' must be a character.") + } else { + if (nchar(tdates) != "17") { + stop("Parameter 'tdates' must be a string with 17 charecters.") + } else { + dateini <- as.Date(substr(tdates,start=1,stop=8),format="%Y%m%d") + dateend <- as.Date(substr(tdates,start=10,stop=18),format="%Y%m%d") + if (dateend <= dateini) { + stop("Parameter 'tdates' must be at least of one day") + } + } + } -#! REANALYSIS GRID PARAMETERS + #! REANALYSIS GRID PARAMETERS rlon <- c(lon, NA) - c(NA, lon) rlon <- rlon[!is.na(rlon)] @@ -261,9 +276,9 @@ if (!is.character(tdates)) { nlon <- ((lon[length(lon)] - lon[1]) / rlon) + 1 ic <- nlat * nlon -# slp_rlon <- c(slp_lon, NA) - c(NA, slp_lon) slp_rlon <- slp_rlon[!is.na(slp_rlon)] + if (!all(slp_rlon == slp_rlon[1])) { stop("Parameter 'slp_lon' must be in regular grid.") } else { @@ -305,230 +320,230 @@ if (!is.character(tdates)) { stop("All 'pred' variables must be in the same period.") } -#!!!!! COMPROBAR QUE SLP TAMBIEN TIENE EL MISMO NROW + #!!!!! COMPROBAR QUE SLP TAMBIEN TIENE EL MISMO NROW seqdates <- seq(as.Date(substr(tdates,start=1,stop=8),format="%Y%m%d"), - as.Date(substr(tdates,start=10,stop=18),format="%Y%m%d"),by="days") + as.Date(substr(tdates,start=10,stop=18),format="%Y%m%d"),by="days") month <- format(seqdates,format="%m") day <- format(seqdates,format="%d") -#! TRAINING REANALYSIS VARIABLES -t1000 <- pred[['t1000']] -msl_si <- pred[['slp']] -msl_lr <- slp_ext - -if (var == "prec") { -u500 <- pred[['u500']] -v500 <- pred[['v500']] -t500 <- pred[['t500']] -t850 <- pred[['t850']] -z500 <- pred[['z500']] -z1000 <- pred[['z1000']] -q700 <- pred[['q700']] -} + #! TRAINING REANALYSIS VARIABLES + t1000 <- pred[['t1000']] + msl_si <- pred[['slp']] + msl_lr <- slp_ext + + if (var == "prec") { + u500 <- pred[['u500']] + v500 <- pred[['v500']] + t500 <- pred[['t500']] + t850 <- pred[['t850']] + z500 <- pred[['z500']] + z1000 <- pred[['z1000']] + q700 <- pred[['q700']] + } -#! HIGH-RESOLUTION (HR) OBSERVATIONAL DATASET -maestro_hr_file <- paste(HR_path, "maestro_red_hr_SPAIN.txt",sep="") -if (!file.exists(maestro_hr_file)) { + #! HIGH-RESOLUTION (HR) OBSERVATIONAL DATASET + maestro_hr_file <- paste(HR_path, "maestro_red_hr_SPAIN.txt",sep="") + if (!file.exists(maestro_hr_file)) { stop("'maestro_red_hr_SPAIN.txt' does not exist.") -} else { + } else { maestro <- read.table(maestro_hr_file) lon_hr <- unlist(maestro[2]) lat_hr <- unlist(maestro[3]) nptos <- length(readLines(maestro_hr_file)) -} + } -if (var == "prec") { - prec_hr_file <- paste(HR_path, "pcp_red_SPAIN_",tdates,".txt",sep="") - if (!file.exists(prec_hr_file)) { - stop(sprintf("precipitation HR file for %s does not exist.",tdates)) - } else { - nd_hr <- length(readLines(prec_hr_file)) - preprec_hr <- matrix(scan(prec_hr_file), nrow=nd_hr ,ncol= nptos+1, byrow=TRUE) - prec_hr <- preprec_hr[1:nd_hr,-c(1)] - } -} else { - tmx_hr_file <- paste(HR_path, "tmx_red_SPAIN_",tdates,".txt",sep="") - tmn_hr_file <- paste(HR_path, "tmn_red_SPAIN_",tdates,".txt",sep="") - if (!file.exists(tmx_hr_file)) { - stop(sprintf("maximum temperature HR file for %s does not exist.",tdates)) - } else if (!file.exists(tmn_hr_file)) { - stop(sprintf("minimum temperature HR file for %s does not exist.",tdates)) - } else if (length(readLines(tmx_hr_file)) != length(readLines(tmn_hr_file))) { - stop("maximum and minimum temperature HR observation files must have the same period.") - } else { - nd_hr <- length(readLines(tmx_hr_file)) - pretmx_hr <- matrix(scan(tmx_hr_file), nrow=nd_hr ,ncol= nptos+1, byrow=TRUE) - tmx_hr <- pretmx_hr[1:nd_hr,-c(1)] - pretmn_hr <- matrix(scan(tmn_hr_file), nrow=nd_hr ,ncol= nptos+1, byrow=TRUE) - tmn_hr <- pretmn_hr[1:nd_hr,-c(1)] - } -} + if (var == "prec") { + prec_hr_file <- paste(HR_path, "pcp_red_SPAIN_",tdates,".txt",sep="") + if (!file.exists(prec_hr_file)) { + stop(sprintf("precipitation HR file for %s does not exist.",tdates)) + } else { + nd_hr <- length(readLines(prec_hr_file)) + preprec_hr <- matrix(scan(prec_hr_file), nrow=nd_hr ,ncol= nptos+1, byrow=TRUE) + prec_hr <- preprec_hr[1:nd_hr,-c(1)] + } + } else { + tmx_hr_file <- paste(HR_path, "tmx_red_SPAIN_",tdates,".txt",sep="") + tmn_hr_file <- paste(HR_path, "tmn_red_SPAIN_",tdates,".txt",sep="") + if (!file.exists(tmx_hr_file)) { + stop(sprintf("maximum temperature HR file for %s does not exist.",tdates)) + } else if (!file.exists(tmn_hr_file)) { + stop(sprintf("minimum temperature HR file for %s does not exist.",tdates)) + } else if (length(readLines(tmx_hr_file)) != length(readLines(tmn_hr_file))) { + stop("maximum and minimum temperature HR observation files must have the same period.") + } else { + nd_hr <- length(readLines(tmx_hr_file)) + pretmx_hr <- matrix(scan(tmx_hr_file), nrow=nd_hr ,ncol= nptos+1, byrow=TRUE) + tmx_hr <- pretmx_hr[1:nd_hr,-c(1)] + pretmn_hr <- matrix(scan(tmn_hr_file), nrow=nd_hr ,ncol= nptos+1, byrow=TRUE) + tmn_hr <- pretmn_hr[1:nd_hr,-c(1)] + } + } if (nd_hr != nd) { stop("Reanalysis variables and HR observations must have the same period.") } -#! OTHER PARAMETERS that should not be changed -#! Number of analog situations to consider -nanx <- 155 -#! Number of predictors -npx <- 11 - -#!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -if (var == "prec") { - - prePro <- .Fortran("training_part1_prec", - u500 = as.numeric(u500), - v500 = as.numeric(v500), - t1000 = as.numeric(t1000), - z500 = as.numeric(z500), - z1000 = as.numeric(z1000), - msl_si = as.numeric(msl_si), - msl_lr = as.numeric(msl_lr), - ngridd = as.integer(ngridd), - nlat = as.integer(nlat), - nlon = as.integer(nlon), - ic = as.integer(ic), - nlatt = as.integer(nlatt), - nlont = as.integer(nlont), - id = as.integer(id), - slat = as.numeric(slat), - slon = as.numeric(slon), - rlat = as.numeric(rlat), - rlon = as.numeric(rlon), - slatt = as.numeric(slatt), - slont = as.numeric(slont), - nd = as.integer(nd), - um = matrix(as.double(seq(1,nd*ic)),c(nd,ic)), - vm = matrix(as.double(seq(1,nd*ic)),c(nd,ic)), - gu92 = matrix(as.double(seq(1,nd*ic)),c(nd,ic)), - gv92 = matrix(as.double(seq(1,nd*ic)),c(nd,ic)), - gu52 = matrix(as.double(seq(1,nd*ic)),c(nd,ic)), - gv52 = matrix(as.double(seq(1,nd*ic)),c(nd,ic)), - nger = as.integer(1), - PACKAGE = 'CSTools') - - a <- prePro$um - b <- prePro$vm - c <- prePro$gu92[1:prePro$nger,] - d <- prePro$gv92[1:prePro$nger,] - e <- prePro$gu52[1:prePro$nger,] - f <- prePro$gv52[1:prePro$nger,] - - g <- prePro$nger - - predSig <- .Fortran("training_part2_prec", - u500 = as.numeric(u500), - v500 = as.numeric(v500), - t500 = as.numeric(t500), - t850 = as.numeric(t850), - msl_si = as.numeric(msl_si), - q700 = as.numeric(q700), - lon_hr = as.numeric(lon_hr), - lat_hr = as.numeric(lat_hr), - prec_hr = as.numeric(prec_hr), - nanx = as.integer(nanx), - nlat = as.integer(nlat), - nlon = as.integer(nlon), - ic = as.integer(ic), - nlatt = as.integer(nlatt), - nlont = as.integer(nlont), - id = as.integer(id), - slat = as.numeric(slat), - slon = as.numeric(slon), - rlat = as.numeric(rlat), - rlon = as.numeric(rlon), - slatt = as.numeric(slatt), - slont = as.numeric(slont), - nd = as.integer(nd), - um = as.double(a), - vm = as.double(b), - gu92 = as.double(c), - gv92 = as.double(d), - gu52 = as.double(e), - gv52 = as.double(f), - nger = as.integer(g), - vdmin = matrix(as.double(seq(1,nptos*4)),c(nptos,4)), - vref = matrix(as.integer(seq(1,nptos*4)),c(nptos,4)), - neni = as.integer(1), - mi = matrix(as.integer(seq(1,prePro$nger*nptos)),c(prePro$nger,nptos)), - ccm = matrix(as.double(seq(1,prePro$nger*nptos)),c(prePro$nger,nptos)), - lab_pred = matrix(as.integer(seq(1,prePro$nger*nptos*npx)),c(prePro$nger,nptos,npx)), - cor_pred = matrix(as.double(seq(1,prePro$nger*nptos*npx)),c(prePro$nger,nptos,npx)), - PACKAGE = 'CSTools') - - h <- predSig$mi - i <- predSig$ccm - j <- predSig$lab_pred - k <- predSig$cor_pred - l <- predSig$vdmin - m <- predSig$vref - - indices <- array(c(j,k),c(g,nptos,npx,2)) - dimnames(indices)[[4]] <- c("lab_pred","cor_pred") - - output <- list("um" = a, - "vm" = b, - "nger" = g, - "gu92" = c, - "gv92" = d, - "gu52" = e, - "gv52" = f, - "neni" = predSig$neni, - "vdmin" = l, - "vref" = m, - "ccm" = i, - "indices" = indices) -} else { - - prePro <- .Fortran("training_temp", - t1000 = as.numeric(t1000), - msl_si = as.numeric(msl_si), - msl_lr = as.numeric(msl_lr), - lon_hr = as.numeric(lon_hr), - lat_hr = as.numeric(lat_hr), - ngridd = as.integer(ngridd), - nlat = as.integer(nlat), - nlon = as.integer(nlon), - ic = as.integer(ic), - nlatt = as.integer(nlatt), - nlont = as.integer(nlont), - id = as.integer(id), - slat = as.numeric(slat), - slon = as.numeric(slon), - rlat = as.numeric(rlat), - rlon = as.numeric(rlon), - slatt = as.numeric(slatt), - slont = as.numeric(slont), - nd = as.integer(nd), - day = as.integer(day), - month = as.integer(month), - um = matrix(as.double(seq(1,nd*ic)),c(nd,ic)), - vm = matrix(as.double(seq(1,nd*ic)),c(nd,ic)), - insol = vector(mode="double",length=nd), - vdmin = matrix(as.double(seq(1,nptos*4)),c(nptos,4)), - vref = matrix(as.integer(seq(1,nptos*4)),c(nptos,4)), - neni = as.integer(1), - PACKAGE = 'CSTools') - - a <- prePro$um - b <- prePro$vm - c <- prePro$insol - d <- prePro$vdmin - e <- prePro$vref - f <- prePro$neni - - output <- list("um" = a, - "vm" = b, - "insol" = c, - "vdmin" = d, - "vref" = e, - "neni" = f) - -} + #! OTHER PARAMETERS that should not be changed + #! Number of analog situations to consider + nanx <- 155 + #! Number of predictors + npx <- 11 + + #!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + if (var == "prec") { + + prePro <- .Fortran("training_part1_prec", + u500 = as.numeric(u500), + v500 = as.numeric(v500), + t1000 = as.numeric(t1000), + z500 = as.numeric(z500), + z1000 = as.numeric(z1000), + msl_si = as.numeric(msl_si), + msl_lr = as.numeric(msl_lr), + ngridd = as.integer(ngridd), + nlat = as.integer(nlat), + nlon = as.integer(nlon), + ic = as.integer(ic), + nlatt = as.integer(nlatt), + nlont = as.integer(nlont), + id = as.integer(id), + slat = as.numeric(slat), + slon = as.numeric(slon), + rlat = as.numeric(rlat), + rlon = as.numeric(rlon), + slatt = as.numeric(slatt), + slont = as.numeric(slont), + nd = as.integer(nd), + um = matrix(as.double(seq(1,nd*ic)),c(nd,ic)), + vm = matrix(as.double(seq(1,nd*ic)),c(nd,ic)), + gu92 = matrix(as.double(seq(1,nd*ic)),c(nd,ic)), + gv92 = matrix(as.double(seq(1,nd*ic)),c(nd,ic)), + gu52 = matrix(as.double(seq(1,nd*ic)),c(nd,ic)), + gv52 = matrix(as.double(seq(1,nd*ic)),c(nd,ic)), + nger = as.integer(1), + PACKAGE = 'CSTools') + + a <- prePro$um + b <- prePro$vm + c <- prePro$gu92[1:prePro$nger,] + d <- prePro$gv92[1:prePro$nger,] + e <- prePro$gu52[1:prePro$nger,] + f <- prePro$gv52[1:prePro$nger,] + + g <- prePro$nger + + predSig <- .Fortran("training_part2_prec", + u500 = as.numeric(u500), + v500 = as.numeric(v500), + t500 = as.numeric(t500), + t850 = as.numeric(t850), + msl_si = as.numeric(msl_si), + q700 = as.numeric(q700), + lon_hr = as.numeric(lon_hr), + lat_hr = as.numeric(lat_hr), + prec_hr = as.numeric(prec_hr), + nanx = as.integer(nanx), + nlat = as.integer(nlat), + nlon = as.integer(nlon), + ic = as.integer(ic), + nlatt = as.integer(nlatt), + nlont = as.integer(nlont), + id = as.integer(id), + slat = as.numeric(slat), + slon = as.numeric(slon), + rlat = as.numeric(rlat), + rlon = as.numeric(rlon), + slatt = as.numeric(slatt), + slont = as.numeric(slont), + nd = as.integer(nd), + um = as.double(a), + vm = as.double(b), + gu92 = as.double(c), + gv92 = as.double(d), + gu52 = as.double(e), + gv52 = as.double(f), + nger = as.integer(g), + vdmin = matrix(as.double(seq(1,nptos*4)),c(nptos,4)), + vref = matrix(as.integer(seq(1,nptos*4)),c(nptos,4)), + neni = as.integer(1), + mi = matrix(as.integer(seq(1,prePro$nger*nptos)),c(prePro$nger,nptos)), + ccm = matrix(as.double(seq(1,prePro$nger*nptos)),c(prePro$nger,nptos)), + lab_pred = matrix(as.integer(seq(1,prePro$nger*nptos*npx)),c(prePro$nger,nptos,npx)), + cor_pred = matrix(as.double(seq(1,prePro$nger*nptos*npx)),c(prePro$nger,nptos,npx)), + PACKAGE = 'CSTools') + + h <- predSig$mi + i <- predSig$ccm + j <- predSig$lab_pred + k <- predSig$cor_pred + l <- predSig$vdmin + m <- predSig$vref + + indices <- array(c(j,k),c(g,nptos,npx,2)) + dimnames(indices)[[4]] <- c("lab_pred","cor_pred") + + output <- list("um" = a, + "vm" = b, + "nger" = g, + "gu92" = c, + "gv92" = d, + "gu52" = e, + "gv52" = f, + "neni" = predSig$neni, + "vdmin" = l, + "vref" = m, + "ccm" = i, + "indices" = indices) + } else { + + prePro <- .Fortran("training_temp", + t1000 = as.numeric(t1000), + msl_si = as.numeric(msl_si), + msl_lr = as.numeric(msl_lr), + lon_hr = as.numeric(lon_hr), + lat_hr = as.numeric(lat_hr), + ngridd = as.integer(ngridd), + nlat = as.integer(nlat), + nlon = as.integer(nlon), + ic = as.integer(ic), + nlatt = as.integer(nlatt), + nlont = as.integer(nlont), + id = as.integer(id), + slat = as.numeric(slat), + slon = as.numeric(slon), + rlat = as.numeric(rlat), + rlon = as.numeric(rlon), + slatt = as.numeric(slatt), + slont = as.numeric(slont), + nd = as.integer(nd), + day = as.integer(day), + month = as.integer(month), + um = matrix(as.double(seq(1,nd*ic)),c(nd,ic)), + vm = matrix(as.double(seq(1,nd*ic)),c(nd,ic)), + insol = vector(mode="double",length=nd), + vdmin = matrix(as.double(seq(1,nptos*4)),c(nptos,4)), + vref = matrix(as.integer(seq(1,nptos*4)),c(nptos,4)), + neni = as.integer(1), + PACKAGE = 'CSTools') + + a <- prePro$um + b <- prePro$vm + c <- prePro$insol + d <- prePro$vdmin + e <- prePro$vref + f <- prePro$neni + + output <- list("um" = a, + "vm" = b, + "insol" = c, + "vdmin" = d, + "vref" = e, + "neni" = f) + + } - return(output) + return(output) } diff --git a/R/BEI_PDFBest.R b/R/BEI_PDFBest.R index 46833b2c57bc716f8459c90bfebb1fac9a189350..d2abc028aa95d1202f2de0030d4b0d244890d075 100644 --- a/R/BEI_PDFBest.R +++ b/R/BEI_PDFBest.R @@ -6,66 +6,68 @@ #'Probability Density Functions (PDFs) (e.g. NAO index) obtained to combining #'the Index PDFs for two Seasonal Forecast Systems (SFSs), the Best Index #'estimation (see Sanchez-Garcia, E. et al (2019), -#'https://doi.org/10.5194/asr-16-165-2019 for more details about the +#'\url{https://doi.org/10.5194/asr-16-165-2019} for more details about the #'methodology applied to estimate the Best Index). #' #'@references Regionally improved seasonal forecast of precipitation through #'Best estimation of winter NAO, Sanchez-Garcia, E. et al., -#' Adv. Sci. Res., 16, 165174, 2019, https://doi.org/10.5194/asr-16-165-2019 +#' Adv. Sci. Res., 16, 165174, 2019, \url{https://doi.org/10.5194/asr-16-165-2019} #' #'@param index_obs Index (e.g. NAO index) array from an observational database -#' or reanalysis with at least a temporal dimension (by default 'time'), -#' which must be greater than 2. +#' or reanalysis with at least a temporal dimension (by default 'time'), +#' which must be greater than 2. #'@param index_hind1 Index (e.g. NAO index) array from a SFS (named SFS1) -#' with at least two dimensions (time , member) or (time, statistic). -#' The temporal dimension, by default 'time', must be greater than 2. -#' The dimension 'member' must be greater than 1. -#' The dimension 'statistic' must be equal to 2, for containing the two paramenters of -#' a normal distribution (mean and sd) representing the ensemble of a SFS. -#' It is not possible to have the dimension 'member' and 'statistic' at the same time. +#' with at least two dimensions (time , member) or (time, statistic). +#' The temporal dimension, by default 'time', must be greater than 2. +#' The dimension 'member' must be greater than 1. The dimension 'statistic' +#' must be equal to 2, for containing the two paramenters of a normal +#' distribution (mean and sd) representing the ensemble of a SFS. It is not +#' possible to have the dimension 'member' and 'statistic' +#' at the same time. #'@param index_hind2 Index (e.g. NAO index) array from a SFS (named SFS2) -#' with at least two dimensions (time , member) or (time, statistic). -#' The temporal dimension, by default 'time', must be greater than 2. -#' The dimension 'member' must be greater than 1. -#' The dimension 'statistic' must be equal to 2, for containing the two paramenters of -#' a normal distribution (mean and sd) representing the ensemble of a SFS. -#' It is not possible to have the dimension 'member' and 'statistic' together. -#'@param index_fcst1 (optional, default = NULL) Index (e.g. NAO index) array from forescating of SFS1 -#' with at least two dimensions (time , member) or (time, statistic). -#' The temporal dimension, by default 'time', must be equal to 1, the forecast year target. -#' The dimension 'member' must be greater than 1. -#' The dimension 'statistic' must be equal to 2, for containing the two paramenters of -#' a normal distribution (mean and sd) representing the ensemble of a SFS. -#' It is not possible to have the dimension 'member' and 'statistic' together. -#'@param index_fcst2 (optional, default = NULL) Index (e.g. NAO index) array from forescating of SFS2 -#' with at least two dimensions (time , member) or (time, statistic). -#' The temporal dimension, by default 'time', must be equal to 1, the forecast year target. -#' The dimension 'member' must be greater than 1. -#' The dimension 'statistic' must be equal to 2, for containing the two paramenters of -#' a normal distribution (mean and sd) representing the ensemble of a SFS. -#' It is not possible to have the dimension 'member' and 'statistic' together. +#' with at least two dimensions (time , member) or (time, statistic). +#' The temporal dimension, by default 'time', must be greater than 2. +#' The dimension 'member' must be greater than 1. +#' The dimension 'statistic' must be equal to 2, for containing the two +#' paramenters of a normal distribution (mean and sd) representing the ensemble +#' of a SFS. It is not possible to have the dimension 'member' and 'statistic' +#' together. +#'@param index_fcst1 (optional, default = NULL) Index (e.g. NAO index) array +#' from forescating of SFS1 with at least two dimensions (time , member) or +#' (time, statistic). The temporal dimension, by default 'time', must be equal +#' to 1, the forecast year target. The dimension 'member' must be greater than +#' 1. The dimension 'statistic' must be equal to 2, for containing the two +#' paramenters of a normal distribution (mean and sd) representing the ensemble +#' of a SFS. It is not possible to have the dimension 'member' and 'statistic' +#' together. +#'@param index_fcst2 (optional, default = NULL) Index (e.g. NAO index) array +#' from forescating of SFS2 with at least two dimensions (time , member) or +#' (time, statistic). The temporal dimension, by default 'time', must be equal +#' to 1, the forecast year target. The dimension 'member' must be greater than +#' 1. The dimension 'statistic' must be equal to 2, for containing the two +#' paramenters of a normal distribution (mean and sd) representing the ensemble +#' of a SFS. It is not possible to have the dimension 'member' and 'statistic' +#' together. #'@param method_BC A character vector of maximun length 2 indicating the bias -#'correction methodology to be applied on each SFS. If it is 'none' or any of -#'its elements is 'none', the bias correction won't be applied. -#'Available methods developped are "ME" (a bias correction scheme based on the -#'mean error or bias between observation and predictions to correct the -#'predicted values), and "LMEV" (a bias correction scheme based on a linear -#'model using ensemble variance of index as predictor). (see Sanchez-Garcia, -#'E. et al (2019), https://doi.org/10.5194/asr-16-165-2019 for more details). +#' correction methodology to be applied on each SFS. If it is 'none' or any of +#' its elements is 'none', the bias correction won't be applied. Available +#' methods developped are "ME" (a bias correction scheme based on the mean +#' error or bias between observation and predictions to correct the predicted +#' values), and "LMEV" (a bias correction scheme based on a linear model using +#' ensemble variance of index as predictor). (see Sanchez-Garcia, E. et al +#' (2019), https://doi.org/10.5194/asr-16-165-2019 for more details). #'@param time_dim_name A character string indicating the name of the temporal -#'dimension, by default 'time'. +#' dimension, by default 'time'. #'@param na.rm Logical (default = FALSE). Should missing values be removed? #' -#' @return BEI_PDFBest() returns an array with the parameters that caracterize -#' the PDFs, with at least a temporal dimension, by default 'time' and dimension -#' 'statistic' equal to 2. -#' The firt statistic is the parameter 'mean' of the PDF for the best estimation -#' combining the two SFSs PDFs. -#' The second statistic is the parameter 'standard deviation' of the PDF for -#' the best estimation combining the two SFSs PDFs. -#' If index_fcst1 and/or index_fcst2 are null, returns the values for hindcast period. -#' Otherwise, it returns the values for a forecast year. -#'@import multiApply +#'@return BEI_PDFBest() returns an array with the parameters that caracterize +#'the PDFs, with at least a temporal dimension, by default 'time' and dimension +#''statistic' equal to 2. The firt statistic is the parameter 'mean' of the PDF +#'for the best estimation combining the two SFSs PDFs. The second statistic is +#'the parameter 'standard deviation' of the PDF for the best estimation +#'combining the two SFSs PDFs. If index_fcst1 and/or index_fcst2 are null, +#'returns the values for hindcast period. Otherwise, it returns the values for a +#'forecast year. #' #'@examples #' # Example 1 for the BEI_PDFBest function @@ -97,12 +99,13 @@ #' index_fcst2 <- rnorm(18, mean = -0.5, sd = 4) #' dim(index_fcst2) <- c(time = 1, member = 9, season = 2) #' method_BC <- c('LMEV', 'ME') -#' res <- BEI_PDFBest(index_obs, index_hind1, index_hind2, index_fcst1, index_fcst2, method_BC) +#' res <- BEI_PDFBest(index_obs, index_hind1, index_hind2, index_fcst1, +#' index_fcst2, method_BC) #' dim(res) #' # time statistic season #' # 1 2 2 +#'@import multiApply #'@export - BEI_PDFBest <- function(index_obs, index_hind1, index_hind2, index_fcst1 = NULL, index_fcst2 = NULL, method_BC = 'none', time_dim_name = 'time', na.rm = FALSE) { @@ -122,7 +125,7 @@ BEI_PDFBest <- function(index_obs, index_hind1, index_hind2, if (!is.character(method_BC) || !is.vector(method_BC)){ stop("Parameter 'method_BC' must be a character vector.") } - if (!(length(method_BC) == 1 || length(method_BC) == 2)){ + if (!(length(method_BC) == 1 || length(method_BC) == 2)) { stop("Length of parameter 'method_BC' must be 1 or 2.") } if(!all(method_BC %in% c('ME', 'LMEV', 'none'))){ @@ -340,23 +343,21 @@ BEI_PDFBest <- function(index_obs, index_hind1, index_hind2, #' Atomic BEI_PDFBest #'@param pdf_1 Statistics array for the first SFS PDF with one dimension -#' 'statistic' equal to 4. -#' @param pdf_2 Statistics array for the second SFS PDF with one dimension -#' 'statistic' equal to 4. -#' @param bc_dataset1 Logical (default = TRUE). -#' If TRUE the Index PDFs for the first SFS has been computed -#' with bias corrected. -#' @param bc_dataset2 Logical (default = TRUE). -#' If TRUE the Index PDFs for the second SFS has been computed -#' with bias corrected. +#' 'statistic' equal to 4. +#'@param pdf_2 Statistics array for the second SFS PDF with one dimension +#' 'statistic' equal to 4. +#'@param bc_dataset1 Logical (default = TRUE). +#' If TRUE the Index PDFs for the first SFS has been computed with bias +#' corrected. +#'@param bc_dataset2 Logical (default = TRUE). If TRUE the Index PDFs for the +#' second SFS has been computed with bias corrected. #' -#' @return .BEI_PDFBest returns an array with dimensions (statistic = 2). -#' The firt statistic is the parameter 'mean' of the PDF for the best estimation -#' combining the two SFSs PDF. -#' The second statistic is the parameter 'standard deviation' of the PDF for -#' the best estimation combining the two SFSs PDF. +#'@return .BEI_PDFBest returns an array with dimensions (statistic = 2). +#'The firt statistic is the parameter 'mean' of the PDF for the best estimation +#'combining the two SFSs PDF. The second statistic is the parameter 'standard +#'deviation' of the PDF for the best estimation combining the two SFSs PDF. #' -#' @examples +#'@examples #' # Example for the Atomic BEI_PDFBest function #' pdf_1 <- c(1.1,0.6,1.6,0.9) #' dim(pdf_1) <- c(statistic = 4) @@ -367,7 +368,7 @@ BEI_PDFBest <- function(index_obs, index_hind1, index_hind2, #' dim(res) #' # statistic #' # 2 -#' @noRd +#'@noRd .BEI_PDFBest <- function(pdf_1, pdf_2, bc_dataset1 = TRUE, bc_dataset2 = TRUE) { if(bc_dataset1){ # apply bias correction to model 1 @@ -404,33 +405,34 @@ BEI_PDFBest <- function(index_obs, index_hind1, index_hind2, #' (e.g. NAO index) to improve the index estimate from SFSs for a hindcast period. #' #'@references Regionally improved seasonal forecast of precipitation through Best -#' estimation of winter NAO, Sanchez-Garcia, E. et al., -#' Adv. Sci. Res., 16, 165174, 2019, https://doi.org/10.5194/asr-16-165-2019 +#'estimation of winter NAO, Sanchez-Garcia, E. et al., +#'Adv. Sci. Res., 16, 165174, 2019, \url{https://doi.org/10.5194/asr-16-165-2019} #' #'@param index_hind Index (e.g. NAO index) array from SFSs -#' with at least two dimensions (time , member) or (time, statistic). -#' The temporal dimension, by default 'time', must be greater than 2. -#' The dimension 'member' must be greater than 1. -#' The dimension 'statistic' must be equal to 2, for containing the two paramenters of -#' a normal distribution (mean and sd) representing the ensemble of a SFS. -#' It is not possible to have the dimension 'member' and 'statistic' together. +#' with at least two dimensions (time , member) or (time, statistic). +#' The temporal dimension, by default 'time', must be greater than 2. +#' The dimension 'member' must be greater than 1. +#' The dimension 'statistic' must be equal to 2, for containing the two +#' paramenters of a normal distribution (mean and sd) representing the ensemble +#' of a SFS. It is not possible to have the dimension 'member' and 'statistic' +#' together. #'@param index_obs Index (e.g. NAO index) array from an observational database -#' or reanalysis with at least a temporal dimension (by default 'time'), -#' which must be greater than 2. +#' or reanalysis with at least a temporal dimension (by default 'time'), +#' which must be greater than 2. #'@param method A character string indicating which methodology is applied -#' to compute the PDFs. One of "ME" (default) or "LMEV". -#'@param time_dim_name A character string indicating the name of the temporal dimension, by default 'time'. +#' to compute the PDFs. One of "ME" (default) or "LMEV". +#'@param time_dim_name A character string indicating the name of the temporal +#' dimension, by default 'time'. #'@param na.rm Logical (default = FALSE). Should missing values be removed? #' -#'@return an array with at least two dimensions (time, statistic = 4). -#' The firt statistic is the parameter 'mean' of the PDF with not bias corrected -#' The second statistic is the parameter 'standard deviation' of the PDF -#' with not bias corrected -#' The third statistic is the parameter 'mean' of the PDF with bias corrected -#' The fourth statistic is the parameter 'standard deviation' of the PDF -#' with bias corrected -#' @import multiApply -#' @examples +#'@return An array with at least two dimensions (time, statistic = 4). The firt +#'statistic is the parameter 'mean' of the PDF with not bias corrected. +#'The second statistic is the parameter 'standard deviation' of the PDF with not +#'bias corrected. The third statistic is the parameter 'mean' of the PDF with +#'bias corrected. The fourth statistic is the parameter 'standard deviation' of +#'the PDF with bias corrected. +#'@import multiApply +#'@examples #' # Example for the PDFIndexHind function #' # Example 1 #' index_obs <- 1 : (5 * 3 ) @@ -529,32 +531,28 @@ PDFIndexHind <- function(index_hind, index_obs, method ='ME', return(PDFstatistics$output1) } - - #' Atomic PDFIndexHind -#' @param index_hind Index (e.g. NAO index) array from a SFS with dimensions -#' (time, member) or (time, statistic) for a hindcast period. -#' The temporal dimension, by default 'time', must be greater -#' than 2. -#' @param index_obs Index (e.g. NAO index) array from an observational dataset -#' or reanalysis with dimension (time). The temporal dimension, -#' by default 'time', must be greater than 2. -#' @param method A character string indicating which methodology is applied -#' to compute the PDF. One of "ME" (default) or "LMEV". -#' @param time_dim_name A character string indicating the name of the temporal dimension, by default 'time'. -#' @param na.rm Logical. Should missing values be removed? -#' @return .PDFIndexHind returns an array with dimensions (time, statistic = 4). -#' The firt statistic is the parameter 'mean' of the PDF with not bias corrected -#' for the hindcast period. -#' The second statistic is the parameter 'standard deviation' of the PDF -#' with not bias corrected for the hindcast period. -#' The third statistic is the parameter 'mean' of the PDF with bias corrected -#' for the hindcast period. -#' The fourth statistic is the parameter 'standard deviation' of the PDF -#' with bias corrected for the hindcast period. -#' @import multiApply -#' @importFrom verification verify -#' @examples +#'@param index_hind Index (e.g. NAO index) array from a SFS with dimensions +#' (time, member) or (time, statistic) for a hindcast period. +#' The temporal dimension, by default 'time', must be greater than 2. +#'@param index_obs Index (e.g. NAO index) array from an observational dataset +#' or reanalysis with dimension (time). The temporal dimension, +#' by default 'time', must be greater than 2. +#'@param method A character string indicating which methodology is applied +#' to compute the PDF. One of "ME" (default) or "LMEV". +#'@param time_dim_name A character string indicating the name of the temporal +#' dimension, by default 'time'. +#'@param na.rm Logical. Should missing values be removed? +#'@return .PDFIndexHind returns an array with dimensions (time, statistic = 4). +#'The firt statistic is the parameter 'mean' of the PDF with not bias corrected +#'for the hindcast period. The second statistic is the parameter 'standard +#'deviation' of the PDF with not bias corrected for the hindcast period. +#'The third statistic is the parameter 'mean' of the PDF with bias corrected +#'for the hindcast period. The fourth statistic is the parameter 'standard +#'deviation' of the PDF with bias corrected for the hindcast period. +#'@import multiApply +#'@importFrom verification verify +#'@examples #' # Example for the Atomic PDFIndexHind function #' index_obs <- 1 : 10 #' dim(index_obs) <- c(time = length(index_obs)) @@ -564,7 +562,7 @@ PDFIndexHind <- function(index_hind, index_obs, method ='ME', #' dim(res) #' # time statistic #' # 10 4 -#' @noRd +#'@noRd .PDFIndexHind <- function(index_hind, index_obs, method = 'ME', time_dim_name = 'time', na.rm = FALSE) { dimnameshind <- names(dim(index_hind)) @@ -630,39 +628,40 @@ PDFIndexHind <- function(index_hind, index_obs, method ='ME', #' #'@references Regionally improved seasonal forecast of precipitation through Best #' estimation of winter NAO, Sanchez-Garcia, E. et al., -#' Adv. Sci. Res., 16, 165174, 2019, https://doi.org/10.5194/asr-16-165-2019 +#' Adv. Sci. Res., 16, 165174, 2019, \url{https://doi.org/10.5194/asr-16-165-2019} #' #'@param index_hind Index (e.g. NAO index) array from SFSs -#' with at least two dimensions (time , member) or (time, statistic). -#' The temporal dimension, by default 'time', must be greater than 2. -#' The dimension 'member' must be greater than 1. -#' The dimension 'statistic' must be equal to 2, for containing the two paramenters of -#' a normal distribution (mean and sd) representing the ensemble of a SFS. -#' It is not possible to have the dimension 'member' and 'statistic' together. +#' with at least two dimensions (time , member) or (time, statistic). +#' The temporal dimension, by default 'time', must be greater than 2. +#' The dimension 'member' must be greater than 1. +#' The dimension 'statistic' must be equal to 2, for containing the two +#' paramenters of a normal distribution (mean and sd) representing the ensemble +#' of a SFS. It is not possible to have the dimension 'member' and 'statistic' +#' together. #'@param index_obs Index (e.g. NAO index) array from an observational database -#' or reanalysis with at least a temporal dimension (by default 'time'), -#' which must be greater than 2. -#'@param index_fcst Index (e.g. NAO index) array from SFSs -#' with at least two dimensions (time , member) or (time, statistic). -#' The temporal dimension, by default 'time', must be equal to 1, the forecast year target. -#' The dimension 'member' must be greater than 1. -#' The dimension 'statistic' must be equal to 2, for containing the two paramenters of -#' a normal distribution (mean and sd) representing the ensemble of a SFS. -#' It is not possible to have the dimension 'member' and 'statistic' together. +#' or reanalysis with at least a temporal dimension (by default 'time'), +#' which must be greater than 2. +#'@param index_fcst Index (e.g. NAO index) array from SFSs with at least two +#' dimensions (time , member) or (time, statistic). The temporal dimension, by +#' default 'time', must be equal to 1, the forecast year target. The dimension +#' 'member' must be greater than 1. The dimension 'statistic' must be equal to +#' 2, for containing the two paramenters of a normal distribution (mean and sd) +#' representing the ensemble of a SFS. It is not possible to have the dimension +#' 'member' and 'statistic' together. #'@param method A character string indicating which methodology is applied -#' to compute the PDFs. One of "ME" (default) or "LMEV". -#'@param time_dim_name A character string indicating the name of the temporal dimension, by default 'time'. +#' to compute the PDFs. One of "ME" (default) or "LMEV". +#'@param time_dim_name A character string indicating the name of the temporal +#' dimension, by default 'time'. #'@param na.rm Logical (default = FALSE). Should missing values be removed? #' -#'@return an array with at least two dimensions (time = 1, statistic = 4). -#' The firt statistic is the parameter 'mean' of the PDF with not bias corrected -#' The second statistic is the parameter 'standard deviation' of the PDF -#' with not bias corrected -#' The third statistic is the parameter 'mean' of the PDF with bias corrected -#' The fourth statistic is the parameter 'standard deviation' of the PDF -#' with bias corrected -#' @import multiApply -#' @examples +#'@return An array with at least two dimensions (time = 1, statistic = 4). +#'The firt statistic is the parameter 'mean' of the PDF with not bias corrected +#'The second statistic is the parameter 'standard deviation' of the PDF with not +#'bias corrected. The third statistic is the parameter 'mean' of the PDF with +#'bias corrected. The fourth statistic is the parameter 'standard deviation' of +#'the PDF with bias corrected. +#'@import multiApply +#'@examples #' # Example for the PDFIndexFcst function #' index_fcst <- 1 : (8 * 4) #' dim(index_fcst) <- c(time = 1, member = 8, season = 4) @@ -787,38 +786,35 @@ PDFIndexFcst <- function(index_hind, index_obs, index_fcst, return(PDFstatistics$output1) } -#' Atomic PDFIndexFcst -#' @param index_hind Index (e.g. NAO index) array from a SFS with dimensions -#' (time, member) or (time, statistic) for a hindcast period. -#' The temporal dimension, by default 'time', must be greater -#' than 2. -#' @param index_obs Index (e.g. NAO index) array from an observational dataset -#' or reanalysis with dimension (time). The temporal dimension, -#' by default 'time', must be greater than 2. -#' @param index_fcst Index (e.g. NAO index) array from SFSs -#' with dimensions (time , member) or (time, statistic). -#' The temporal dimension, by default 'time', must be equal to 1, -#' the forecast year target. -#' The dimension 'member' must be greater than 1. -#' The dimension 'statistic' must be equal to 2, for containing the two paramenters of -#' a normal distribution (mean and sd) representing the ensemble of a SFS. -#' It is not possible to have the dimension 'member' and 'statistic' together. -#' @param method A character string indicating which methodology is applied -#' to compute the PDF. One of "ME" (default) or "LMEV". -#' @param time_dim_name A character string indicating the name of the temporal dimension, by default 'time'. -#' @param na.rm Logical. Should missing values be removed? -#' @return .PDFIndexFcst returns an array with dimensions (time = 1, statistic=4). -#' The firt statistic is the parameter 'mean' of the PDF with not bias corrected -#' for the forecast year. -#' The second statistic is the parameter 'standard deviation' of the PDF -#' with not bias corrected for the forecast year. -#' The third statistic is the parameter 'mean' of the PDF with bias corrected -#' for the forecast year. -#' The fourth statistic is the parameter 'standard deviation' of the PDF -#' with bias corrected for the forecast year. -#' @import multiApply -#' @importFrom verification verify -#' @examples +#'Atomic PDFIndexFcst +#'@param index_hind Index (e.g. NAO index) array from a SFS with dimensions +#' (time, member) or (time, statistic) for a hindcast period. The temporal +#' dimension, by default 'time', must be greater than 2. +#'@param index_obs Index (e.g. NAO index) array from an observational dataset +#' or reanalysis with dimension (time). The temporal dimension, by default +#' 'time', must be greater than 2. +#'@param index_fcst Index (e.g. NAO index) array from SFSs with dimensions +#' (time , member) or (time, statistic). The temporal dimension, by default +#' 'time', must be equal to 1, the forecast year target. The dimension 'member' +#' must be greater than 1. The dimension 'statistic' must be equal to 2, for +#' containing the two paramenters of a normal distribution (mean and sd) +#' representing the ensemble of a SFS. It is not possible to have the dimension +#' 'member' and 'statistic' together. +#'@param method A character string indicating which methodology is applied +#' to compute the PDF. One of "ME" (default) or "LMEV". +#'@param time_dim_name A character string indicating the name of the temporal +#' dimension, by default 'time'. +#'@param na.rm Logical. Should missing values be removed? +#'@return .PDFIndexFcst Returns an array with dimensions +#'(time = 1, statistic = 4). The firt statistic is the parameter 'mean' of the +#'PDF with not bias corrected for the forecast year. The second statistic is the +#'parameter 'standard deviation' of the PDF with not bias corrected for the +#'forecast year. The third statistic is the parameter 'mean' of the PDF with +#'bias corrected for the forecast year. The fourth statistic is the parameter +#''standard deviation' of the PDF with bias corrected for the forecast year. +#'@import multiApply +#'@importFrom verification verify +#'@examples #' # Example 1 for the Atomic PDFIndexFcst function #' index_fcst <- 1 : (1 * 6) #' dim(index_fcst) <- c(time = 1, member = 6) diff --git a/R/BEI_Weights.R b/R/BEI_Weights.R index 63fb22c311618ecbe8e9259203ccc4796c7d9d9c..40b32ded560512df1b6ef0ea052bb1cdd6066752 100644 --- a/R/BEI_Weights.R +++ b/R/BEI_Weights.R @@ -3,26 +3,26 @@ #'@author Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} #' #'@description This function implements the computation to obtain the -#' normalized weights for each member of each Seasonal Forecast Systems (SFS) -#' or dataset using the Probability Density Functions (PDFs) indicated by the -#' parameter 'pdf_weight' (for instance the Best Index estimation obtained -#' using the 'PDFBest' function). The weight of each member is proportional to -#' the probability of its index calculated with the PDF "pdf_weight". +#'normalized weights for each member of each Seasonal Forecast Systems (SFS) +#'or dataset using the Probability Density Functions (PDFs) indicated by the +#'parameter 'pdf_weight' (for instance the Best Index estimation obtained +#'using the 'PDFBest' function). The weight of each member is proportional to +#'the probability of its index calculated with the PDF "pdf_weight". #' -#'@references Regionally improved seasonal forecast of precipitation through Best -#' estimation of winter NAO, Sanchez-Garcia, E. et al., -#' Adv. Sci. Res., 16, 165174, 2019, https://doi.org/10.5194/asr-16-165-2019 +#'@references Regionally improved seasonal forecast of precipitation through +#'Best estimation of winter NAO, Sanchez-Garcia, E. et al., +#'Adv. Sci. Res., 16, 165174, 2019, \url{https://doi.org/10.5194/asr-16-165-2019} #' #'@param index_weight Index (e.g. NAO index) array, from a dataset of SFSs -#' for a period of years, with at least dimensions 'member'. -#' Additional dimensions, for instance, a temporal dimension as 'time', -#' must have the same lenght in both parameters, -#' 'index_weight' and 'pdf_weight'. -#' @param pdf_weight Statistics array to define a Gaussian PDF with at least -#' dimensions 'statistic'. -#' The firt statistic is the parameter 'mean' of the PDF and -#' the second statistic is the parameter 'standard deviation' of the PDF. -#' @param time_dim_name A character string indicating the name of the temporal dimension, by default 'time'. +#' for a period of years, with at least dimensions 'member'. +#' Additional dimensions, for instance, a temporal dimension as 'time', +#' must have the same lenght in both parameters, 'index_weight' and +#' 'pdf_weight'. +#'@param pdf_weight Statistics array to define a Gaussian PDF with at least +#' dimensions 'statistic'. The firt statistic is the parameter 'mean' of the PDF +#' and the second statistic is the parameter 'standard deviation' of the PDF. +#'@param time_dim_name A character string indicating the name of the temporal +#' dimension, by default 'time'. #' #'@return BEI_Weights() returns a normalized weights array with the same #' dimensions that index_weight. @@ -98,16 +98,16 @@ BEI_Weights <- function(index_weight, pdf_weight, time_dim_name = 'time') { return(aweights) } -#' Atomic BEI_Weights -#' @param index_weight Index (e.g. NAO index) array from a SFS with dimensions -#' (member) -#' @param pdf_weight Statistics array to define a Gaussian PDF with dimensions -#' (statistic = 2). -#' The firt statistic is the parameter 'mean' of the PDF and -#' the second statistic is the parameter 'standard deviation' of the PDF. -#' @return .BEI_Weights returns an array of with dimensions (member), -#' the normalized weights for each member of a SFS using a Best NAO PDF. -#' @examples +#'Atomic BEI_Weights +#'@param index_weight Index (e.g. NAO index) array from a SFS with dimensions +#' (member) +#'@param pdf_weight Statistics array to define a Gaussian PDF with dimensions +#' (statistic = 2). +#' The firt statistic is the parameter 'mean' of the PDF and +#' the second statistic is the parameter 'standard deviation' of the PDF. +#'@return .BEI_Weights returns an array of with dimensions (member), +#'the normalized weights for each member of a SFS using a Best NAO PDF. +#'@examples #' # Example for the Atomic BEI_Weights function #' index_weight <- c(1.3,3,-1) #' dim(index_weight) <- c(member = 3) @@ -117,7 +117,7 @@ BEI_Weights <- function(index_weight, pdf_weight, time_dim_name = 'time') { #' dim(res) #' # member #' # 3 -#' @noRd +#'@noRd .BEI_Weights <- function(index_weight, pdf_weight) { aweights <- apply(index_weight, 1, dnorm, mean = pdf_weight[1], sd = pdf_weight[2]) dim(aweights) <- dim(index_weight) diff --git a/R/CST_AdamontAnalog.R b/R/CST_AdamontAnalog.R index 4020d1c265f1d6fc33ecfc8f26e6b1764a4743b8..81951f1e1ec0349f4ad1ec0e6a01e11c5b17e637 100644 --- a/R/CST_AdamontAnalog.R +++ b/R/CST_AdamontAnalog.R @@ -8,36 +8,39 @@ #'@author Lauriane Batté, \email{lauriane.batte@meteo.fr} for CSTools adaptation #' #'@param exp \itemize{ -#'\item\code{CST_AdamontAnalog}{experiment data an object of class \code{s2dv_cube}, can be output -#'from quantile correction using CST_AdamontQQCorr} -#'\item\code{AdamontAnalog}{experiment data array with named dimension}} -#'@param wt_exp corresponding weather types (same dimensions as \code{exp$data} -#'but lat/lon) +#' \item\code{CST_AdamontAnalog}{experiment data an object of class +#' \code{s2dv_cube}, can be output from quantile correction using +#' CST_AdamontQQCorr.} +#' \item\code{AdamontAnalog}{experiment data array with named dimension.}} +#'@param wt_exp Corresponding weather types (same dimensions as \code{exp$data} +#' but lat/lon). #'@param obs \itemize{ -#'\item\code{CST_AdamontAnalog}{reference data, also of class \code{s2dv_cube}.} -#'\item\code{AdamontAnalog}{reference data array with named dimension.}} -#'Note that lat/lon dimensions need to be the same as \code{exp} -#'@param wt_obs corresponding weather types (same dimensions as \code{obs$data} -#'but lat/lon) -#'@param nanalogs integer defining the number of analog values to return -#'(default: 5) -#'@param method a character string indicating the method used for analog -#'definition -#' Coded are 'pattcorr': pattern correlation -#' 'rain1' (for precip patterns): rain occurrence consistency -#' 'rain01' (for precip patterns): rain occurrence/non -#' occurrence consistency -#'@param thres real number indicating the threshold to define rain -#'occurrence/non occurrence in rain(0)1 -#'@param search_obsdims list of dimensions in \code{obs} along which analogs are -#'searched for -#'@param londim name of longitude dimension -#'@param latdim name of latitude dimension +#' \item\code{CST_AdamontAnalog}{reference data, also of class \code{s2dv_cube}.} +#' \item\code{AdamontAnalog}{reference data array with named dimension.}} +#' Note that lat/lon dimensions need to be the same as \code{exp} +#'@param wt_obs Corresponding weather types (same dimensions as \code{obs$data} +#' but lat/lon) +#'@param nanalogs Integer defining the number of analog values to return +#' (default: 5) +#'@param method A character string indicating the method used for analog +#' definition. Coded are: +#' \itemize{ +#' \item{'pattcorr': pattern correlation.} +#' \item{'rain1' (for precip patterns): rain occurrence consistency.} +#' \item{'rain01' (for precip patterns): rain occurrence/non occurrence +#' consistency} +#' } +#'@param thres Real number indicating the threshold to define rain +#' occurrence/non occurrence in rain(0)1 +#'@param search_obsdims List of dimensions in \code{obs} along which analogs are +#' searched for. +#'@param londim Name of longitude dimension. +#'@param latdim Name of latitude dimension. #'@return analog_vals #'\itemize{ -#'\item\code{CST_AdamontAnalog}{an object of class \code{s2dv_cube} containing nanalogs -#'analog values for each value of \code{exp} input data} -#'\item\code{AdamontAnalog}{an array containing nanalogs analog values}} +#' \item\code{CST_AdamontAnalog}{An object of class \code{s2dv_cube} containing +#' nanalogs analog values for each value of \code{exp} input data.} +#' \item\code{AdamontAnalog}{An array containing nanalogs analog values.}} #'@import multiApply #'@importFrom ClimProjDiags Subset #'@examples @@ -46,7 +49,8 @@ #'dim(wt_exp) <- c(dataset=1, member=15, sdate=6, ftime=3) #'wt_obs <- sample(1:3, 6*3, replace=T) #'dim(wt_obs) <- c(dataset=1, member=1, sdate=6, ftime=3) -# analog_vals <- CST_AdamontAnalog(exp=lonlat_temp$exp, obs=lonlat_temp$obs, wt_exp=wt_exp, wt_obs=wt_obs, nanalogs=2) +#'analog_vals <- CST_AdamontAnalog(exp = lonlat_temp$exp, obs = lonlat_temp$obs, +#' wt_exp = wt_exp, wt_obs = wt_obs, nanalogs = 2) #'} #'\dontrun{ #'wt_exp <- sample(1:3, 15*6*3, replace=T) @@ -56,41 +60,40 @@ # analog_vals <- AdamontAnalog(exp=lonlat_temp$exp$data, #' obs=lonlat_temp$obs$data, wt_exp=wt_exp, wt_obs=wt_obs, nanalogs=2) #'} - +#'@export CST_AdamontAnalog <- function(exp, obs, wt_exp, wt_obs, nanalogs, method = 'pattcorr', thres = NULL, search_obsdims = c('member', 'sdate', 'ftime'), londim = 'lon', latdim = 'lat') { - dimnames <- names(dim(obs$data)) dimnamesexp <- names(dim(exp$data)) if (!inherits(exp, 's2dv_cube') || !inherits(obs, 's2dv_cube')) { - stop("Inputs 'exp' and 'obs' must be of class 's2dv_cube', ", - "as output by CSTools::CST_Load.") + stop("Inputs 'exp' and 'obs' must be of class 's2dv_cube', ", + "as output by CSTools::CST_Load.") } if (!(method %in% c('pattcorr','rain1','rain01'))) { - stop("Input parameter 'method' must be 'pattcorr', 'rain1', or 'rain01'") + stop("Input parameter 'method' must be 'pattcorr', 'rain1', or 'rain01'") } if (is.null(nanalogs)){ nanalogs <- 5 } if (!(latdim %in% dimnames) || !(londim %in% dimnames)){ - stop("'londim' or 'latdim' input doesn't match with 'obs$data' dimension", - " names") + stop("'londim' or 'latdim' input doesn't match with 'obs$data' dimension", + " names") } if (!(latdim %in% dimnamesexp) || !(londim %in% dimnamesexp)){ - stop("'londim' or 'latdim' input doesn't match with 'exp$data' dimension", - " names") + stop("'londim' or 'latdim' input doesn't match with 'exp$data' dimension", + " names") } - if (!all(search_obsdims %in% dimnames)){ - stop("Names in parameter 'search_obsdims' should match 'obs$data' ", - "dimension names.") + if (!all(search_obsdims %in% dimnames)) { + stop("Names in parameter 'search_obsdims' should match 'obs$data' ", + "dimension names.") } - if (!all(dim(wt_exp) %in% dim(exp$data))){ - stop("Dimensions for 'wt_exp' should match 'exp$data' except lat/lon") + if (!all(dim(wt_exp) %in% dim(exp$data))) { + stop("Dimensions for 'wt_exp' should match 'exp$data' except lat/lon") } - if (!all(dim(wt_obs) %in% dim(obs$data))){ - stop("Dimensions for 'wt_obs' should match 'obs$data' except lat/lon") + if (!all(dim(wt_obs) %in% dim(obs$data))) { + stop("Dimensions for 'wt_obs' should match 'obs$data' except lat/lon") } plat_exp <- which(dimnamesexp==latdim) plon_exp <- which(dimnamesexp==londim) @@ -99,15 +102,14 @@ CST_AdamontAnalog <- function(exp, obs, wt_exp, wt_obs, nanalogs, if ((dim(obs$data)[plon_obs]!=dim(exp$data)[plon_exp]) || (dim(obs$data)[plat_obs]!=dim(exp$data)[plat_exp])){ stop("Element 'data' from parameters 'obs' and 'exp' should have", - "same lon / lat dimensions if working with regular grids.") + "same lon / lat dimensions if working with regular grids.") } # End of sanity checks; call AdamontAnalog function analog_vals <- AdamontAnalog(exp = exp$data, obs = obs$data, wt_exp = wt_exp, - wt_obs=wt_obs, nanalogs = nanalogs, - method = method, thres = thres, - search_obsdims = search_obsdims, londim = londim, - latdim = latdim ) - + wt_obs = wt_obs, nanalogs = nanalogs, + method = method, thres = thres, + search_obsdims = search_obsdims, londim = londim, + latdim = latdim ) return(analog_vals) } @@ -118,10 +120,10 @@ CST_AdamontAnalog <- function(exp, obs, wt_exp, wt_obs, nanalogs, #'@importFrom ClimProjDiags Subset #'@rdname CST_AdamontAnalog #'@export -AdamontAnalog <- function(exp, obs, wt_exp, wt_obs, nanalogs=5, - method = 'pattcorr', thres = NULL, - search_obsdims = c('member', 'sdate', 'ftime'), - londim = 'lon', latdim = 'lat') { +AdamontAnalog <- function(exp, obs, wt_exp, wt_obs, nanalogs=5, + method = 'pattcorr', thres = NULL, + search_obsdims = c('member', 'sdate', 'ftime'), + londim = 'lon', latdim = 'lat') { # exp: lat, lon, sdate, ftime, member # obs: lat, lon, dims for searching 'sdate' 'ftime'... # wt_exp: sdate, ftime, member @@ -129,13 +131,13 @@ AdamontAnalog <- function(exp, obs, wt_exp, wt_obs, nanalogs=5, dimnames <- names(dim(obs)) dimnamesexp <- names(dim(exp)) if (method %in% c('rain1','rain01') & is.null(thres)){ - stop("Threshold 'thres' must be defined with methods 'rain1' and 'rain01'") + stop("Threshold 'thres' must be defined with methods 'rain1' and 'rain01'") } if (method == 'pattcorr' & !is.null(thres)){ - warning("Parameter 'thres' is not used with method 'pattcorr'.") + warning("Parameter 'thres' is not used with method 'pattcorr'.") } if (!(latdim %in% dimnamesexp) || !(londim %in% dimnamesexp)){ - stop("'londim' or 'latdim' input doesn't match with 'exp' dimension names") + stop("'londim' or 'latdim' input doesn't match with 'exp' dimension names") } # Position of lat/lon dimensions in exp data poslatexp <- which(dimnamesexp == latdim) @@ -143,18 +145,18 @@ AdamontAnalog <- function(exp, obs, wt_exp, wt_obs, nanalogs=5, poslatobs <- which(dimnames == latdim) poslonobs <- which(dimnames == londim) if (!all(search_obsdims %in% dimnames)){ - stop("Names in parameter 'search_obsdims' should match 'obs' ", - "dimension names.") + stop("Names in parameter 'search_obsdims' should match 'obs' ", + "dimension names.") } if (!all(dim(wt_exp) %in% dim(exp))){ - stop("Dimensions for 'wt_exp' should match 'exp' except lat/lon") + stop("Dimensions for 'wt_exp' should match 'exp' except lat/lon") } if (!all(dim(wt_obs) %in% dim(obs))){ - stop("Dimensions for 'wt_obs' should match 'obs' except lat/lon") + stop("Dimensions for 'wt_obs' should match 'obs' except lat/lon") } if ((dim(obs)[poslonobs]!=dim(exp)[poslonexp]) || (dim(obs)[poslatobs]!=dim(exp)[poslatexp])){ - stop("Parameters 'obs' and 'exp' should have same lon / lat dimensions.") + stop("Parameters 'obs' and 'exp' should have same lon / lat dimensions.") } ## Reshaping obs: @@ -162,9 +164,9 @@ AdamontAnalog <- function(exp, obs, wt_exp, wt_obs, nanalogs=5, if (length(search_obsdims) > 1) { for (i in 1:(length(search_obsdims) - 1)) { obs <- MergeDims(obs, search_obsdims[i:(i + 1)], - rename_dim = search_obsdims[i + 1]) + rename_dim = search_obsdims[i + 1]) wt_obs <- MergeDims(wt_obs, search_obsdims[i:(i + 1)], - rename_dim = search_obsdims[i + 1]) + rename_dim = search_obsdims[i + 1]) } } names(dim(obs))[which(names(dim(obs)) == search_obsdims[length(search_obsdims)])] <- 'time' @@ -180,17 +182,17 @@ AdamontAnalog <- function(exp, obs, wt_exp, wt_obs, nanalogs=5, .analogs, method = method, thres = thres)$output1 # Reshaping output: - analog_vals <- Subset(analog_vals,along='type',indices=1,drop='selected') + analog_vals <- Subset(analog_vals, along = 'type', indices = 1, drop = 'selected') poslat <- which(names(dim(analog_vals)) == latdim) poslon <- which(names(dim(analog_vals)) == londim) postime <- which(names(dim(analog_vals)) == 'time') # Dimension with N analogs pos <- 1:length(dim(analog_vals)) if (poslatexp > poslonexp){ analog_vals <- aperm(analog_vals,c(pos[-c(poslon,poslat,postime)], - postime,poslon,poslat)) + postime,poslon,poslat)) } else { analog_vals <- aperm(analog_vals,c(pos[-c(poslon,poslat,postime)], - postime,poslat,poslon)) + postime,poslat,poslon)) } # Renaming 'time' dim to 'analog' names(dim(analog_vals))[which(names(dim(analog_vals)) == 'time')] <- 'analog' @@ -199,16 +201,16 @@ AdamontAnalog <- function(exp, obs, wt_exp, wt_obs, nanalogs=5, .analogs <- function(exp, obs, wt_exp, nanalogs = 5, method = 'pattcorr', - thres = NULL, londimexp = 'lon', latdimexp = 'lat', - londimobs = 'lon', latdimobs = 'lat') { + thres = NULL, londimexp = 'lon', latdimexp = 'lat', + londimobs = 'lon', latdimobs = 'lat') { # exp: lon, lat # obs: lon, lat, time, wt # wt_exp: wt single scalar search_analog <- switch(method, 'rain1' = .rain1, 'rain01' = .rain01, - 'pattcorr' = .pattcor, + 'pattcorr' = .pattcor, stop(paste0("Adamont Analog function only supports ", - "methods 'rain1', 'rain01', 'pattcorr'"))) + "methods 'rain1', 'rain01', 'pattcorr'"))) obs <- Subset(obs, along = 'type', indices = wt_exp) accuracy <- Apply(list(exp, obs), target_dims = list(c(londimexp, latdimexp), diff --git a/R/CST_AdamontQQCorr.R b/R/CST_AdamontQQCorr.R index 71a768e21437283e5134241aab9eefd61d8e4734..ac6c07b37e133c37a185b1bbfd188f681e71fcf8 100644 --- a/R/CST_AdamontQQCorr.R +++ b/R/CST_AdamontQQCorr.R @@ -8,25 +8,25 @@ #'@author Paola Marson, \email{paola.marson@meteo.fr} #'@author Gildas Dayon, \email{gildas.dayon@meteo.fr} #' -#'@param exp experiment data an object of class \code{s2dv_cube} -#'@param wt_exp corresponding weather types (same dimensions as \code{exp$data} -#' but lat/lon) -#'@param obs reference data, also of class \code{s2dv_cube}. lat/lon dimensions -#' can differ from \code{exp} if non rectilinear latlon grids are used, -#' in which case regrid should be set to TRUE and .NearestNeighbors \code{NN} -#' output should be provided -#'@param wt_obs corresponding weather types (same dimensions as \code{obs} but -#'lat/lon) -#'@param corrdims list of dimensions in \code{exp} for which quantile mapping -#' correction is applied -#'@param londim character name of longitude dimension in \code{exp} and -#' \code{obs} -#'@param latdim character name of latitude dimension in \code{exp} and -#' \code{obs} +#'@param exp Experiment data an object of class \code{s2dv_cube}. +#'@param wt_exp Corresponding weather types (same dimensions as \code{exp$data} +#' but lat/lon). +#'@param obs Reference data, also of class \code{s2dv_cube}. lat/lon dimensions +#' can differ from \code{exp} if non rectilinear latlon grids are used, +#' in which case regrid should be set to TRUE and .NearestNeighbors \code{NN} +#' output should be provided. +#'@param wt_obs Corresponding weather types (same dimensions as \code{obs} but +#' lat/lon). +#'@param corrdims List of dimensions in \code{exp} for which quantile mapping +#' correction is applied. +#'@param londim Character name of longitude dimension in \code{exp} and +#' \code{obs}. +#'@param latdim Character name of latitude dimension in \code{exp} and +#' \code{obs}. #' -#'@return an object of class \code{s2dv_cube} containing experiment data on the -#' lat/lon grid of \code{obs} input data, corrected by quantile mapping -#' depending on the weather types \code{wt_exp} +#'@return An object of class \code{s2dv_cube} containing experiment data on the +#'lat/lon grid of \code{obs} input data, corrected by quantile mapping +#'depending on the weather types \code{wt_exp}. #' #'@import qmap #'@importFrom ClimProjDiags Subset @@ -43,8 +43,8 @@ #' corrdims = c('dataset','member','sdate','ftime')) #'} CST_AdamontQQCorr <- function(exp, wt_exp, obs, wt_obs, - corrdims = c('member','sdate','ftime'), - londim='lon', latdim='lat') { + corrdims = c('member','sdate','ftime'), + londim = 'lon', latdim = 'lat') { if (!inherits(exp, 's2dv_cube') || !inherits(obs, 's2dv_cube')){ stop("Inputs 'exp' and 'obs' must be of class 's2dv_cube', ", @@ -108,29 +108,29 @@ CST_AdamontQQCorr <- function(exp, wt_exp, obs, wt_obs, #'@author Paola Marson, \email{paola.marson@meteo.fr} for PROSNOW version #'@author Lauriane Batté, \email{lauriane.batte@meteo.fr} for CSTools adaptation #' -#'@param exp array with named dimensions (such as \code{$data} array of -#'experiment data from an object of class \code{s2dv_cube}) -#'@param wt_exp corresponding weather types (same dimensions as \code{exp} but -#'lat/lon) -#'@param obs array with named dimensions with reference data (can also be -#'\code{$data} array of class \code{s2dv_cube}). lat/lon dimensions can differ -#'from \code{exp} if non rectilinear latlon grids are used, in which case -#'regrid should be set to TRUE and .NearestNeighbors \code{NN} output should be -#'provided -#'@param wt_obs corresponding weather types (same dimensions as \code{obs} but -#'lat/lon) -#'@param corrdims list of dimensions in \code{exp} for which quantile mapping -#'correction is applied -#'@param londim character name of longitude dimension in \code{exp} and -#'\code{obs} -#'@param latdim character name of latitude dimension in \code{exp} and -#'\code{obs} -#'@param regrid (optional) boolean indicating whether .NearestNeighbors -#'regridding is needed -#'@param NN (optional, if regrid=TRUE) list (output from .NearestNeighbors) -#'maps (nlat, nlon) onto (nlat_o, nlon_o) +#'@param exp Array with named dimensions (such as \code{$data} array of +#' experiment data from an object of class \code{s2dv_cube}). +#'@param wt_exp Corresponding weather types (same dimensions as \code{exp} but +#' lat/lon). +#'@param obs Array with named dimensions with reference data (can also be +#' \code{$data} array of class \code{s2dv_cube}). lat/lon dimensions can differ +#' from \code{exp} if non rectilinear latlon grids are used, in which case +#' regrid should be set to TRUE and .NearestNeighbors \code{NN} output should +#' be provided. +#'@param wt_obs Corresponding weather types (same dimensions as \code{obs} but +#' lat/lon). +#'@param corrdims List of dimensions in \code{exp} for which quantile mapping +#' correction is applied. +#'@param londim Character name of longitude dimension in \code{exp} and +#' \code{obs}. +#'@param latdim Character name of latitude dimension in \code{exp} and +#' \code{obs}. +#'@param regrid (optional) Boolean indicating whether .NearestNeighbors +#' regridding is needed. +#'@param NN (optional, if regrid = TRUE) List (output from .NearestNeighbors) +#' maps (nlat, nlon) onto (nlat_o, nlon_o). #' -#'@return an array (such as \code{$data} array from an object of class +#'@return An array (such as \code{$data} array from an object of class #'\code{s2dv_cube}) with named dimensions, containing experiment data on the #'lat/lon grid of \code{obs} array, corrected by quantile mapping depending on #'the weather types \code{wt_exp} @@ -142,16 +142,18 @@ CST_AdamontQQCorr <- function(exp, wt_exp, obs, wt_obs, #'@examples #'\dontrun{ #'wt_exp <- sample(1:3, 15*6*3, replace=T) -#'dim(wt_exp) <- c(dataset=1, member=15, sdate=6, ftime=3) -#'wt_obs <- sample(1:3, 6*3, replace=T) -#'dim(wt_obs) <- c(dataset=1, member=1, sdate=6, ftime=3) -#'exp_corr <- AdamontQQCorr(exp=lonlat_temp$exp$data, wt_exp=wt_exp, -#' obs=lonlat_temp$obs$data, wt_obs=wt_obs, -#' corrdims = c('dataset','member','sdate','ftime')) +#'dim(wt_exp) <- c(dataset = 1, member = 15, sdate = 6, ftime = 3) +#'wt_obs <- sample(1:3, 6*3, replace = T) +#'dim(wt_obs) <- c(dataset = 1, member = 1, sdate = 6, ftime = 3) +#'exp_corr <- AdamontQQCorr(exp = lonlat_temp$exp$data, wt_exp = wt_exp, +#' obs = lonlat_temp$obs$data, wt_obs = wt_obs, +#' corrdims = c('dataset','member','sdate','ftime')) #'} +#'@export AdamontQQCorr <- function(exp, wt_exp, obs, wt_obs, - corrdims = c('member', 'sdate', 'ftime'), - londim='lon', latdim='lat', regrid=FALSE, NN=NULL) { + corrdims = c('member', 'sdate', 'ftime'), + londim = 'lon', latdim = 'lat', regrid = FALSE, + NN = NULL) { dimnames <- names(dim(obs)) dimnamesexp <- names(dim(exp)) @@ -291,22 +293,38 @@ AdamontQQCorr <- function(exp, wt_exp, obs, wt_obs, names(dim(new)) <- dimnames return(new) } -#' ADAMONT Nearest Neighbors computes the distance between reference data grid centroid and SF data grid +#'ADAMONT Nearest Neighbors computes the distance between reference data grid +#'centroid and SF data grid #' #'@author Paola Marson, \email{paola.marson@meteo.fr} for PROSNOW version -#'@author Lauriane Batté, \email{lauriane.batte@meteo.fr} for CSTools adaptation -#'@description This function computes the nearest neighbor for each reference data (lon, lat) point in the experiment dataset by computing the distance between the reference dataset grid and the experiment data. This is the first step in the ADAMONT method adapted from Verfaillie et al. (2018). +#'@author Lauriane Batté, \email{lauriane.batte@meteo.fr} for CSTools adaptation +#'@description This function computes the nearest neighbor for each reference +#'data (lon, lat) point in the experiment dataset by computing the distance +#'between the reference dataset grid and the experiment data. This is the first +#'step in the ADAMONT method adapted from Verfaillie et al. (2018). #' -#'@param method a string among three options ('ADA': standard ADAMONT distance, 'simple': lon/lat straight euclidian distance, 'radius': distance on the sphere) -#'@param exp an object of class \code{s2dv_cube} as returned by \code{CST_Load} function, containing the seasonal forecast experiment longitudes in \code{$lon} and latitudes in \code{$lat} -#'@param obs an object of class \code{s2dv_cube} as returned by \code{CST_Load} function, containing the reference data on a different grid, with longitudes in \code{$lon} and latitudes in \code{$lat}. +#'@param method A string among three options ('ADA': standard ADAMONT distance, +#' 'simple': lon/lat straight euclidian distance, 'radius': distance on the +#' sphere). +#'@param exp An object of class \code{s2dv_cube} as returned by \code{CST_Load} +#' function, containing the seasonal forecast experiment longitudes in +#' \code{$lon} and latitudes in \code{$lat}. +#'@param obs An object of class \code{s2dv_cube} as returned by \code{CST_Load} +#' function, containing the reference data on a different grid, with longitudes +#' in \code{$lon} and latitudes in \code{$lat}. #' #'@return NN a list, containing the following: -#' min_lon: array of dimensions \code{obs$lon} giving the longitude of closest gridpoint in exp -#' min_lat: array of dimensions \code{obs$lat} giving the latitude of closest gridpoint in exp -#' imin_lon: array of dimensions \code{obs$lon} giving the longitude index of closest gridpoint in exp -#' imin_lat: array of dimensions \code{obs$lat} giving the latitude index of closest gridpoint in exp -#' +#'\itemize{ +#' \item{'min_lon': array of dimensions \code{obs$lon} giving the longitude of +#' closest gridpoint in exp.} +#' \item{'min_lat': array of dimensions \code{obs$lat} giving the latitude of +#' closest gridpoint in exp.} +#' \item{'imin_lon': array of dimensions \code{obs$lon} giving the longitude +#' index of closest gridpoint in exp.} +#' \item{'imin_lat': array of dimensions \code{obs$lat} giving the latitude +#' index of closest gridpoint in exp.} +#'} +#' #'@importFrom ClimProjDiags Subset #'@import ncdf4 #'@noRd diff --git a/R/CST_Analogs.R b/R/CST_Analogs.R index 6437868091a5b8c9e4f9731dc32953ffbcee159a..6b46d00ef3f0bcee2583160e541ffe7ad1f61db1 100644 --- a/R/CST_Analogs.R +++ b/R/CST_Analogs.R @@ -99,7 +99,7 @@ #' best analog, for instance for downscaling. #'@param ncores The number of cores to use in parallel computation #' -#'@seealso code{\link{CST_Load}}, \code{\link[s2dv]{Load}} and +#'@seealso \code{\link{CST_Load}}, \code{\link[s2dv]{Load}} and #'\code{\link[s2dv]{CDORemap}} #' #'@return An 's2dv_cube' object containing an array with the dowscaled values of @@ -252,10 +252,10 @@ CST_Analogs <- function(expL, obsL, expVar = NULL, obsVar = NULL, region = NULL, #' the same latitudinal and longitudinal dimensions as parameter 'expL' and a #' single temporal dimension with the maximum number of available observations. #'@param time_obsL A character string indicating the date of the observations -#' in the format "dd/mm/yyyy". Reference time to search for analogs. +#' in the format "dd-mm-yyyy". Reference time to search for analogs. #'@param time_expL An array of N named dimensions (coinciding with time #' dimensions in expL) of character string(s) indicating the date(s) of the -#' experiment in the format "dd/mm/yyyy". Time(s) to find the analogs. +#' experiment in the format "dd-mm-yyyy". Time(s) to find the analogs. #'@param lonL A vector containing the longitude of parameter 'expL'. #'@param latL A vector containing the latitude of parameter 'expL'. #'@param excludeTime An array of N named dimensions (coinciding with time @@ -454,18 +454,18 @@ Analogs <- function(expL, obsL, time_obsL, time_expL = NULL, if (is.null(time_expL)) { stop("Parameter 'time_expL' cannot be NULL") } - if(any(class(time_obsL)!="character")){ + if (!inherits(time_obsL, "character")) { warning('imposing time_obsL to be a character') - time_obsL=format(as.Date(time_obsL),'%d-%m-%Y') + time_obsL <- format(as.Date(time_obsL), '%d-%m-%Y') } - if(any(class(time_expL)!="character")){ + if (!inherits(time_expL, "character")) { warning('imposing time_expL to be a character') - time_expL=format(as.Date(time_expL),'%d-%m-%Y') + time_expL <- format(as.Date(time_expL), '%d-%m-%Y') } - if(!is.null(excludeTime)){ - if(any(class(excludeTime)!="character")){ + if (!is.null(excludeTime)) { + if (!inherits(excludeTime, "character")) { warning('imposing excludeTime to be a character') - excludeTime=format(as.Date(excludeTime),'%d-%m-%Y') + excludeTime <- format(as.Date(excludeTime),'%d-%m-%Y') } } if (is.null(time_obsL)) { @@ -589,8 +589,7 @@ Analogs <- function(expL, obsL, time_obsL, time_expL = NULL, c('ftime', 'leadtime', 'ltime') == TRUE)) > 1) { stop("Parameter 'expL' cannot have multiple forecast time dimensions") } else { - names(dim(expL))[which(names(dim(expL)) %in% c('ftime','leadtime','ltime'))] <- - 'time' + names(dim(expL))[which(names(dim(expL)) %in% c('ftime','leadtime','ltime'))] <- 'time' } } # remove dimension length 1 to simplify outputs: diff --git a/R/CST_AnalogsPredictors.R b/R/CST_AnalogsPredictors.R index a15a4c0cab79b383293dcbd4c34de41b95a8a19c..f114e8cbdc89fa7547236319d937d101112a9433 100644 --- a/R/CST_AnalogsPredictors.R +++ b/R/CST_AnalogsPredictors.R @@ -5,840 +5,826 @@ #'@author Marta Dominguez Alonso - AEMET, \email{mdomingueza@aemet.es} #'@author Nuria Perez-Zanon - BSC, \email{nuria.perez@bsc.es} #' -#'@description This function downscales low resolution precipitation data (e.g. from -#' Seasonal Forecast Models) through the association with an observational high -#' resolution (HR) dataset (AEMET 5 km gridded data of daily precipitation (Peral et al., 2017)) -#' and a collection of predictors and past synoptic situations similar to estimated day. -#' The method uses three domains: -#' - peninsular Spain and Balearic Islands domain (5 km resolution): HR precipitation -#' and the downscaling result domain. -#' - synoptic domain (low resolution, e.g. 1.5º x 1.5º): it should be centered over Iberian Peninsula -#' and cover enough extension to detect as much synoptic situations as possible. -#' - extended domain (low resolution, e.g. 1.5º x 1.5º): it should have the same resolution -#' as synoptic domain. It is used for SLP Seasonal Forecast Models. -#'@param exp List of arrays with downscaled period seasonal forecast data. The list -#' has to contain model atmospheric variables (instantaneous 12h data) that must -#' be indentify by parenthesis name. -#' For precipitation: -#' - u component of wind at 500 hPa (u500_mod) in m/s -#' - v component of wind at 500 hPa (v500_mod) in m/s -#' - temperature at 500 hPa (t500_mod) in K -#' - temperature at 850 hPa (t850_mod) in K -#' - specific humidity at 700 hPa (q700_mod) in g/kg -#' For temperature: -#' - u component of wind at 500 hPa (u500_mod) in m/s -#' - v component of wind at 500 hPa (v500_mod) in m/s -#' - temperature at 500 hPa (t500_mod) in K -#' - temperature at 700 hPa (t700_mod) in K -#' - temperature at 850 hPa (t850_mod) in K -#' - specific humidity at 700 hPa (q700_mod) in g/kg -#' - 2 meters temperature (tm2m_mod) in K -#' The arrays must have at least three dimensions with names 'lon', 'lat' and 'time'. -#' (lon = gridpoints of longitude, lat = gridpoints of latitude, time = number of downscaling days) -#' Seasonal forecast variables must have the same resolution and -#' domain as reanalysis variables ('obs' parameter, below). +#'@description This function downscales low resolution precipitation data (e.g. +#'from Seasonal Forecast Models) through the association with an observational +#'high resolution (HR) dataset (AEMET 5 km gridded data of daily precipitation +#'(Peral et al., 2017)) and a collection of predictors and past synoptic +#'situations similar to estimated day. The method uses three domains: +#'\itemize{ +#' \item{Peninsular Spain and Balearic Islands domain (5 km resolution): HR precipitation +#' and the downscaling result domain.} +#' \item{Synoptic domain (low resolution, e.g. 1.5º x 1.5º): it should be +#' centered over Iberian Peninsula and cover enough extension to detect +#' as much synoptic situations as possible.} +#' \item{Extended domain (low resolution, e.g. 1.5º x 1.5º): it should have the +#' same resolution as synoptic domain. It is used for SLP Seasonal +#' Forecast Models.} +#' } +#' +#'@param exp List of arrays with downscaled period seasonal forecast data. The +#' list has to contain model atmospheric variables (instantaneous 12h data) +#' that must be indentify by parenthesis name. For precipitation: +#' \itemize{ +#' \item{u component of wind at 500 hPa (u500_mod) in m/s.} +#' \item{v component of wind at 500 hPa (v500_mod) in m/s.} +#' \item{temperature at 500 hPa (t500_mod) in K.} +#' \item{temperature at 850 hPa (t850_mod) in K.} +#' \item{specific humidity at 700 hPa (q700_mod) in g/kg. } +#' } +#' For temperature: +#' \itemize{ +#' \item{u component of wind at 500 hPa (u500_mod) in m/s.} +#' \item{v component of wind at 500 hPa (v500_mod) in m/s.} +#' \item{temperature at 500 hPa (t500_mod) in K.} +#' \item{temperature at 700 hPa (t700_mod) in K. } +#' \item{temperature at 850 hPa (t850_mod) in K.} +#' \item{specific humidity at 700 hPa (q700_mod) in g/kg. } +#' \item{2 meters temperature (tm2m_mod) in K.} +#' } +#' The arrays must have at least three dimensions with names 'lon', 'lat' and +#' 'time'. (lon = gridpoints of longitude, lat = gridpoints of latitude, +#' time = number of downscaling days) Seasonal forecast variables must have the +#' same resolution and domain as reanalysis variables ('obs' parameter, below). #'@param slp Array with atmospheric seasonal forecast model sea level pressure -#' (instantaneous 12h data) that must be indentify as 'slp' (hPa). It has the same -#' resolution as 'exp' and 'obs' paremeters but with an extended domain. -#' This domain contains extra degrees (most in the north and west part) compare to -#' synoptic domain. The array must have at least three dimensions -#' with names 'lon', 'lat' and 'time'. +#' (instantaneous 12h data) that must be indentify as 'slp' (hPa). It has the +#' same resolution as 'exp' and 'obs' paremeters but with an extended domain. +#' This domain contains extra degrees (most in the north and west part) compare +#' to synoptic domain. The array must have at least three dimensions with +#' names 'lon', 'lat' and 'time'. #'@param obs List of arrays with training period reanalysis data. -#' The list has to contain reanalysis atmospheric variables (instantaneous -#' 12h data) that must be indentify by parenthesis name. -#' For precipitation: -#' - u component of wind at 500 hPa (u500) in m/s -#' - v component of wind at 500 hPa (v500) in m/s -#' - temperature at 500 hPa (t500) in K -#' - temperature at 850 hPa (t850) in K -#' - sea level pressure (slp) in hPa -#' - specific humidity at 700 hPa (q700) in g/kg -#' For maximum and minimum temperature: -#' - u component of wind at 500 hPa (u500) in m/s -#' - v component of wind at 500 hPa (v500) in m/s -#' - temperature at 500 hPa (t500) in K -#' - temperature at 700 hPa (t700) in K -#' - temperature at 850 hPa (t850) in K -#' - sea level pressure (slp) in hPa -#' - specific humidity at 700 hPa (q700) in g/kg -#' - 2 meters temperature (tm2m) in K -#' The arrays must have at least three dimensions with names 'lon', 'lat' and 'time'. +#' The list has to contain reanalysis atmospheric variables (instantaneous +#' 12h data) that must be indentify by parenthesis name. For precipitation: +#' \itemize{ +#' \item{u component of wind at 500 hPa (u500) in m/s.} +#' \item{v component of wind at 500 hPa (v500) in m/s.} +#' \item{temperature at 500 hPa (t500) in K.} +#' \item{temperature at 850 hPa (t850) in K.} +#' \item{sea level pressure (slp) in hPa.} +#' \item{specific humidity at 700 hPa (q700) in g/kg.} +#' } +#' For maximum and minimum temperature: +#' \itemize{ +#' \item{u component of wind at 500 hPa (u500) in m/s.} +#' \item{v component of wind at 500 hPa (v500) in m/s.} +#' \item{temperature at 500 hPa (t500) in K.} +#' \item{temperature at 700 hPa (t700) in K.} +#' \item{temperature at 850 hPa (t850) in K.} +#' \item{sea level pressure (slp) in hPa.} +#' \item{specific humidity at 700 hPa (q700) in g/kg} +#' \item{2 meters temperature (tm2m) in K} +#' } +#' The arrays must have at least three dimensions with names 'lon', 'lat' and +#' 'time'. #'@param lon Vector of the synoptic longitude (from (-180º) to 180º), -#' The vector must go from west to east. The same as for the training function. -#'@param lat Vector of the synoptic latitude. The vector must go from north to south. -#' The same as for the training function. +#' The vector must go from west to east. The same as for the training function. +#'@param lat Vector of the synoptic latitude. The vector must go from north to +#' south. The same as for the training function. #'@param slp_lon Vector of the extended longitude (from (-180º) to 180º), -#' The vector must go from west to east. The same as for the training function. -#'@param slp_lat Vector of the extended latitude. The vector must go from north to south. -#' The same as for the training function. +#' The vector must go from west to east. The same as for the training function. +#'@param slp_lat Vector of the extended latitude. The vector must go from north +#' to south. The same as for the training function. #'@param var_name Variable name to downscale. There are two options: 'prec' for -#' precipitation and 'temp' for maximum and minimum temperature. +#' precipitation and 'temp' for maximum and minimum temperature. #'@param hr_obs Local path of HR observational files (maestro and pcp/tmx-tmn). -#' For precipitation can be downloaded from http://www.aemet.es/documentos/es/serviciosclimaticos/cambio_climat/datos_diarios/dato_observacional/rejilla_5km/v2/Serie_AEMET_v2_pcp_1951a202006_txt.tar.gz -#' For maximum and minimum temperature can be downloaded from http://www.aemet.es/documentos/es/serviciosclimaticos/cambio_climat/datos_diarios/dato_observacional/rejilla_5km/temperatura/v1/tmax/Serie_AEMET_v1_tmax_1951a202006_txt.tar.gz and http://www.aemet.es/documentos/es/serviciosclimaticos/cambio_climat/datos_diarios/dato_observacional/rejilla_5km/temperatura/v1/tmin/Serie_AEMET_v1_tmin_1951a202006_txt.tar.gz respetively. -#' Maestro file (maestro_red_hr_SPAIN.txt) has gridpoint (nptos), longitude (lon), latitude (lat) and -#' altitude (alt) in columns (vector structure). -#' Data file (pcp/tmx/tmn_red_SPAIN_1951-201903.txt) includes 5km resolution spanish daily data -#' (precipitation or maximum and minimum temperature from january 1951 to june 2020. See README -#' file for more information. -#' IMPORTANT!: HR observational period must be the same as for reanalysis variables. -#' It is assumed that the training period is smaller than the HR original one (1951-2019), so it is -#' needed to make a new ascii file with the new period and the same structure as original, -#' specifying the training dates in the name (e.g. 'pcp_red_SPAIN_19810101-19961231.txt' for -#' '19810101-19961231' period). +#' For precipitation and temperature can be downloaded from the following link: +#' \url{https://www.aemet.es/en/serviciosclimaticos/cambio_climat/datos_diarios?w=2} +#' respetively. Maestro file (maestro_red_hr_SPAIN.txt) has gridpoint (nptos), +#' longitude (lon), latitude (lat) and altitude (alt) in columns (vector +#' structure). Data file (pcp/tmx/tmn_red_SPAIN_1951-201903.txt) includes 5km +#' resolution spanish daily data (precipitation or maximum and minimum +#' temperature from january 1951 to june 2020. See README file for more +#' information. IMPORTANT!: HR observational period must be the same as for +#' reanalysis variables. It is assumed that the training period is smaller than +#' the HR original one (1951-2019), so it is needed to make a new ascii file +#' with the new period and the same structure as original, specifying the +#' training dates in the name +#' (e.g. 'pcp_red_SPAIN_19810101-19961231.txt' for '19810101-19961231' period). #'@param tdates Training period dates in format YYYYMMDD(start)-YYYYMMDD(end) -#' (e.g. 19810101-20181231). -#'@param ddates Downscaling period dates in format YYYYMMDD(start)-YYYYMMDD(end) (e.g. 20191001-20200331). -#'@param restrain Output (list of matrix) obtained from 'training_analogs' function. -#' For precipitation, 'restrain' object must contains um, vm, nger, gu92, gv92, -#' gu52, gv52, neni, vdmin, vref, ccm, lab_pred and cor_pred variables. -#' For maximum and minimum temperature, 'restrain' object must contains um, vm, -#' insol, neni, vdmin y vref. See 'AnalogsPred_train.R' for more information. -#'@param dim_name_longitude A character string indicating the name of the longitude -#'dimension, by default 'longitude'. -#'@param dim_name_latitude A character string indicating the name of the latitude -#'dimension, by default 'latitude'. +#' (e.g. 19810101-20181231). +#'@param ddates Downscaling period dates in format YYYYMMDD(start)-YYYYMMDD(end) +#' (e.g. 20191001-20200331). +#'@param restrain Output (list of matrix) obtained from 'training_analogs' +#' function. For precipitation, 'restrain' object must contains um, vm, nger, +#' gu92, gv92, gu52, gv52, neni, vdmin, vref, ccm, lab_pred and cor_pred +#' variables. For maximum and minimum temperature, 'restrain' object must +#' contains um, vm, insol, neni, vdmin y vref. See 'AnalogsPred_train.R' for +#' more information. +#'@param dim_name_longitude A character string indicating the name of the +#' longitude dimension, by default 'longitude'. +#'@param dim_name_latitude A character string indicating the name of the +#' latitude dimension, by default 'latitude'. #'@param dim_name_time A character string indicating the name of the time -#'dimension, by default 'time'. -#'@return Matrix with seasonal forecast precipitation (mm) or -#' maximum and minimum temperature (dozens of ºC) in a 5km x 5km regular grid -#' over peninsular Spain and Balearic Islands. The resulted matrices have two -#' dimensions ('ddates' x 'nptos').(ddates = number of downscaling days -#' and nptos = number of 'hr_obs' gridpoints). +#' dimension, by default 'time'. +#'@return Matrix with seasonal forecast precipitation (mm) or maximum and +#'minimum temperature (dozens of ºC) in a 5km x 5km regular grid over peninsular +#'Spain and Balearic Islands. The resulted matrices have two dimensions +#'('ddates' x 'nptos').(ddates = number of downscaling days and nptos = number +#'of 'hr_obs' gridpoints). #' #'@useDynLib CSTools -#' #'@export -#' -CST_AnalogsPredictors <- function(exp, - slp, - obs, - lon, - lat, - slp_lon, - slp_lat, - var_name, - hr_obs, - tdates, - ddates, - restrain, - dim_name_longitude = "lon", - dim_name_latitude = "lat", - dim_name_time = "time") { - -if (!is.list(exp)) { +CST_AnalogsPredictors <- function(exp, slp, obs, lon, lat, slp_lon, slp_lat, + var_name, hr_obs, tdates, ddates, restrain, + dim_name_longitude = "lon", + dim_name_latitude = "lat", + dim_name_time = "time") { + if (!is.list(exp)) { stop("Parameter 'exp' must be a list of 'array' objects") } -if (!(all(sapply(exp, inherits, 'array')))) { - stop("Elements of the list in parameter 'exp' must be of the class ", - "'array'.") + if (!(all(sapply(exp, inherits, 'array')))) { + stop("Elements of the list in parameter 'exp' must be of the class ", + "'array'.") } -if (!is.array(slp)) { - stop("Parameter 'slp' must be of the class 'array'.") + if (!is.array(slp)) { + stop("Parameter 'slp' must be of the class 'array'.") } -if (!is.list(obs)) { + if (!is.list(obs)) { stop("Parameter 'obs' must be a list of 'array' objects") } -if (!(all(sapply(obs, inherits, 'array')))) { - stop("Elements of the list in parameter 'obs' must be of the class ", + if (!(all(sapply(obs, inherits, 'array')))) { + stop("Elements of the list in parameter 'obs' must be of the class ", "'array'.") } -if (var_name == "prec") { - if (length(exp) != 5) { - stop("Parameter 'exp' must be a length of 5.") - } else { - if (!(any(names(exp) %in% "u500_mod"))) { - stop("Variable 'u500_mod' in 'exp' parameter is missed.") - } else if (!(any(names(exp) %in% "v500_mod"))) { - stop("Variable 'v500_mod' in 'exp' parameter is missed.") - } else if (!(any(names(exp) %in% "t500_mod"))) { - stop("Variable 't500_mod' in 'exp' parameter is missed.") - } else if (!(any(names(exp) %in% "t850_mod"))) { - stop("Variable 't850_mod' in 'exp' parameter is missed.") - } else if (!(any(names(exp) %in% "q700_mod"))) { - stop("Variable 'q700_mod' in 'exp' parameter is missed.") - } - } - if (length(obs) != 6) { - stop("Parameter 'obs' must be a length of 6.") - } else { - if (!(any(names(obs) %in% "u500"))) { - stop("Variable 'u500' in 'obs' parameter is missed.") - } else if (!(any(names(obs) %in% "v500"))) { - stop("Variable 'v500' in 'obs' parameter is missed.") - } else if (!(any(names(obs) %in% "t500"))) { - stop("Variable 't500' in 'obs' parameter is missed.") - } else if (!(any(names(obs) %in% "t850"))) { - stop("Variable 't850' in 'obs' parameter is missed.") - } else if (!(any(names(obs) %in% "slp"))) { - stop("Variable 'slp' in 'obs' parameter is missed.") - } else if (!(any(names(obs) %in% "q700"))) { - stop("Variable 'q700' in 'obs' parameter is missed.") - } - } -} else { - if (length(exp) != 7) { - stop("Parameter 'exp' must be a length of 7.") - } else { - if (!(any(names(exp) %in% "u500_mod"))) { - stop("Variable 'u500_mod' in 'exp' parameter is missed.") - } else if (!(any(names(exp) %in% "v500_mod"))) { - stop("Variable 'v500_mod' in 'exp' parameter is missed.") - } else if (!(any(names(exp) %in% "t500_mod"))) { - stop("Variable 't500_mod' in 'exp' parameter is missed.") - } else if (!(any(names(exp) %in% "t700_mod"))) { - stop("Variable 't700_mod' in 'exp' parameter is missed.") - } else if (!(any(names(exp) %in% "t850_mod"))) { - stop("Variable 't850_mod' in 'exp' parameter is missed.") - } else if (!(any(names(exp) %in% "q700_mod"))) { - stop("Variable 'q700_mod' in 'exp' parameter is missed.") - } else if (!(any(names(exp) %in% "tm2m_mod"))) { - stop("Variable 'tm2m_mod' in 'exp' parameter is missed.") - } - } - if (length(obs) != 8) { - stop("Parameter 'obs' must be a length of 8.") - } else { - if (!(any(names(obs) %in% "u500"))) { - stop("Variable 'u500' in 'obs' parameter is missed.") - } else if (!(any(names(obs) %in% "v500"))) { - stop("Variable 'v500' in 'obs' parameter is missed.") - } else if (!(any(names(obs) %in% "t500"))) { - stop("Variable 't500' in 'obs' parameter is missed.") - } else if (!(any(names(obs) %in% "t700"))) { - stop("Variable 't700' in 'obs' parameter is missed.") - } else if (!(any(names(obs) %in% "t850"))) { - stop("Variable 't850' in 'obs' parameter is missed.") - } else if (!(any(names(obs) %in% "slp"))) { - stop("Variable 'slp' in 'obs' parameter is missed.") - } else if (!(any(names(obs) %in% "q700"))) { - stop("Variable 'q700' in 'obs' parameter is missed.") - } else if (!(any(names(obs) %in% "tm2m"))) { - stop("Variable 'tm2m' in 'obs' parameter is missed.") - } - } -} + if (var_name == "prec") { + if (length(exp) != 5) { + stop("Parameter 'exp' must be a length of 5.") + } else { + if (!(any(names(exp) %in% "u500_mod"))) { + stop("Variable 'u500_mod' in 'exp' parameter is missed.") + } else if (!(any(names(exp) %in% "v500_mod"))) { + stop("Variable 'v500_mod' in 'exp' parameter is missed.") + } else if (!(any(names(exp) %in% "t500_mod"))) { + stop("Variable 't500_mod' in 'exp' parameter is missed.") + } else if (!(any(names(exp) %in% "t850_mod"))) { + stop("Variable 't850_mod' in 'exp' parameter is missed.") + } else if (!(any(names(exp) %in% "q700_mod"))) { + stop("Variable 'q700_mod' in 'exp' parameter is missed.") + } + } + if (length(obs) != 6) { + stop("Parameter 'obs' must be a length of 6.") + } else { + if (!(any(names(obs) %in% "u500"))) { + stop("Variable 'u500' in 'obs' parameter is missed.") + } else if (!(any(names(obs) %in% "v500"))) { + stop("Variable 'v500' in 'obs' parameter is missed.") + } else if (!(any(names(obs) %in% "t500"))) { + stop("Variable 't500' in 'obs' parameter is missed.") + } else if (!(any(names(obs) %in% "t850"))) { + stop("Variable 't850' in 'obs' parameter is missed.") + } else if (!(any(names(obs) %in% "slp"))) { + stop("Variable 'slp' in 'obs' parameter is missed.") + } else if (!(any(names(obs) %in% "q700"))) { + stop("Variable 'q700' in 'obs' parameter is missed.") + } + } + } else { + if (length(exp) != 7) { + stop("Parameter 'exp' must be a length of 7.") + } else { + if (!(any(names(exp) %in% "u500_mod"))) { + stop("Variable 'u500_mod' in 'exp' parameter is missed.") + } else if (!(any(names(exp) %in% "v500_mod"))) { + stop("Variable 'v500_mod' in 'exp' parameter is missed.") + } else if (!(any(names(exp) %in% "t500_mod"))) { + stop("Variable 't500_mod' in 'exp' parameter is missed.") + } else if (!(any(names(exp) %in% "t700_mod"))) { + stop("Variable 't700_mod' in 'exp' parameter is missed.") + } else if (!(any(names(exp) %in% "t850_mod"))) { + stop("Variable 't850_mod' in 'exp' parameter is missed.") + } else if (!(any(names(exp) %in% "q700_mod"))) { + stop("Variable 'q700_mod' in 'exp' parameter is missed.") + } else if (!(any(names(exp) %in% "tm2m_mod"))) { + stop("Variable 'tm2m_mod' in 'exp' parameter is missed.") + } + } + if (length(obs) != 8) { + stop("Parameter 'obs' must be a length of 8.") + } else { + if (!(any(names(obs) %in% "u500"))) { + stop("Variable 'u500' in 'obs' parameter is missed.") + } else if (!(any(names(obs) %in% "v500"))) { + stop("Variable 'v500' in 'obs' parameter is missed.") + } else if (!(any(names(obs) %in% "t500"))) { + stop("Variable 't500' in 'obs' parameter is missed.") + } else if (!(any(names(obs) %in% "t700"))) { + stop("Variable 't700' in 'obs' parameter is missed.") + } else if (!(any(names(obs) %in% "t850"))) { + stop("Variable 't850' in 'obs' parameter is missed.") + } else if (!(any(names(obs) %in% "slp"))) { + stop("Variable 'slp' in 'obs' parameter is missed.") + } else if (!(any(names(obs) %in% "q700"))) { + stop("Variable 'q700' in 'obs' parameter is missed.") + } else if (!(any(names(obs) %in% "tm2m"))) { + stop("Variable 'tm2m' in 'obs' parameter is missed.") + } + } + } -if (all((sapply(exp,dim))==dim(exp[[1]]))) { + if (all((sapply(exp,dim)) == dim(exp[[1]]))) { dim_exp <- dim(exp[[1]]) - if (!(any(names(dim_exp) %in% dim_name_longitude))) { - stop("Dimension 'lon' in exp parameter is missed.") - } - if (!(any(names(dim_exp) %in% dim_name_latitude))) { - stop("Dimension 'lat' in exp parameter is missed.") - } - if (!(any(names(dim_exp) %in% dim_name_time))) { - stop("Dimension 'time' in exp parameter is missed.") - } -} else { - stop("All 'exp' variables must have the same dimensions.") -} + if (!(any(names(dim_exp) %in% dim_name_longitude))) { + stop("Dimension 'lon' in exp parameter is missed.") + } + if (!(any(names(dim_exp) %in% dim_name_latitude))) { + stop("Dimension 'lat' in exp parameter is missed.") + } + if (!(any(names(dim_exp) %in% dim_name_time))) { + stop("Dimension 'time' in exp parameter is missed.") + } + } else { + stop("All 'exp' variables must have the same dimensions.") + } -dim_slp <- dim(slp) -if (!(any(names(dim_slp) %in% dim_name_longitude))) { + dim_slp <- dim(slp) + if (!(any(names(dim_slp) %in% dim_name_longitude))) { stop("Dimension 'lon' in slp parameter is missed.") -} -if (!(any(names(dim_slp) %in% dim_name_latitude))) { + } + if (!(any(names(dim_slp) %in% dim_name_latitude))) { stop("Dimension 'lat' in slp parameter is missed.") -} -if (!(any(names(dim_slp) %in% dim_name_time))) { + } + if (!(any(names(dim_slp) %in% dim_name_time))) { stop("Dimension 'time' in slp parameter is missed.") -} + } -if (all((sapply(obs,dim))==dim(obs[[1]]))) { - dim_obs <- dim(obs[[1]]) - if (!(any(names(dim_obs) %in% dim_name_longitude))) { - stop("Dimension 'lon' in obs parameter is missed.") - } - if (!(any(names(dim_obs) %in% dim_name_latitude))) { - stop("Dimension 'lat' in obs parameter is missed.") - } - if (!(any(names(dim_obs) %in% dim_name_time))) { - stop("Dimension 'time' in obs parameter is missed.") - } -} else { - stop("All 'obs' variables must have the same dimensions.") -} + if (all((sapply(obs,dim))==dim(obs[[1]]))) { + dim_obs <- dim(obs[[1]]) + if (!(any(names(dim_obs) %in% dim_name_longitude))) { + stop("Dimension 'lon' in obs parameter is missed.") + } + if (!(any(names(dim_obs) %in% dim_name_latitude))) { + stop("Dimension 'lat' in obs parameter is missed.") + } + if (!(any(names(dim_obs) %in% dim_name_time))) { + stop("Dimension 'time' in obs parameter is missed.") + } + } else { + stop("All 'obs' variables must have the same dimensions.") + } -if (!is.vector(lon) || !is.numeric(lon)) { + if (!is.vector(lon) || !is.numeric(lon)) { stop("Parameter 'lon' must be a numeric vector") -} else { + } else { if (is.unsorted(lon)) { - lon <- sort(lon) - warning("'lon' vector has been sorted in increasing order") + lon <- sort(lon) + warning("'lon' vector has been sorted in increasing order") } -} + } -if (!is.vector(lat) || !is.numeric(lat)) { + if (!is.vector(lat) || !is.numeric(lat)) { stop("Parameter 'lat' must be a numeric vector") -} else { + } else { if (!is.unsorted(lat)) { - lat <- sort(lat, decreasing = TRUE) - warning("'lat' vector has been sorted in decreasing order") + lat <- sort(lat, decreasing = TRUE) + warning("'lat' vector has been sorted in decreasing order") } -} + } -if (!is.vector(slp_lon) || !is.numeric(slp_lon)) { + if (!is.vector(slp_lon) || !is.numeric(slp_lon)) { stop("Parameter 'slp_lon' must be a numeric vector") -} else { + } else { if (is.unsorted(slp_lon)) { - lon <- sort(slp_lon) - warning("'slp_lon' vector has been sorted in increasing order") + lon <- sort(slp_lon) + warning("'slp_lon' vector has been sorted in increasing order") } -} + } -if (!is.vector(slp_lat) || !is.numeric(slp_lat)) { + if (!is.vector(slp_lat) || !is.numeric(slp_lat)) { stop("Parameter 'slp_lat' must be a numeric vector") -} else { + } else { if (!is.unsorted(slp_lat)) { - lat <- sort(slp_lat, decreasing = TRUE) - warning("'slp_lat' vector has been sorted in decreasing order") + lat <- sort(slp_lat, decreasing = TRUE) + warning("'slp_lat' vector has been sorted in decreasing order") } -} + } -if (!is.character(hr_obs)){ + if (!is.character(hr_obs)){ stop("Parameter 'hr_obs' must be a character.") -} else { - if (!dir.exists(hr_obs)) { - stop("'hr_obs' directory does not exist") - } -} - -if (!is.character(tdates)) { - stop("Parameter 'tdates' must be a character.") -} else { - if (nchar(tdates) != "17") { - stop("Parameter 'tdates' must be a string with 17 charecters.") - } else { - dateini <- as.Date(substr(tdates,start=1,stop=8),format="%Y%m%d") - dateend <- as.Date(substr(tdates,start=10,stop=18),format="%Y%m%d") - if (dateend <= dateini) { - stop("Parameter 'tdates' must be at least of one day") - } - } -} + } else { + if (!dir.exists(hr_obs)) { + stop("'hr_obs' directory does not exist") + } + } -if (!is.character(ddates)) { - stop("Parameter 'ddates' must be a character.") -} else { - if (nchar(ddates) != "17") { - stop("Parameter 'ddates' must be a string with 17 charecters.") - } else { - dateini <- as.Date(substr(ddates,start=1,stop=8),format="%Y%m%d") - dateend <- as.Date(substr(ddates,start=10,stop=18),format="%Y%m%d") - if (dateend <= dateini) { - stop("Parameter 'ddates' must be at least of one day") - } - } -} + if (!is.character(tdates)) { + stop("Parameter 'tdates' must be a character.") + } else { + if (nchar(tdates) != "17") { + stop("Parameter 'tdates' must be a string with 17 charecters.") + } else { + dateini <- as.Date(substr(tdates,start = 1, stop = 8), format = "%Y%m%d") + dateend <- as.Date(substr(tdates,start = 10, stop = 18), format = "%Y%m%d") + if (dateend <= dateini) { + stop("Parameter 'tdates' must be at least of one day") + } + } + } -# + if (!is.character(ddates)) { + stop("Parameter 'ddates' must be a character.") + } else { + if (nchar(ddates) != "17") { + stop("Parameter 'ddates' must be a string with 17 charecters.") + } else { + dateini <- as.Date(substr(ddates, start = 1, stop = 8), format = "%Y%m%d") + dateend <- as.Date(substr(ddates, start = 10, stop = 18), format = "%Y%m%d") + if (dateend <= dateini) { + stop("Parameter 'ddates' must be at least of one day") + } + } + } -if (names(dim(exp[[1]]))[1] == "lon" & names(dim(exp[[1]]))[2] == "lat" - || names(dim(exp[[1]]))[2] == "lon" & names(dim(exp[[1]]))[3] == "lat") { - texp2D <- lapply(exp, MergeDims, merge_dims = c('lon', 'lat'), - rename_dim = 'gridpoint') -} else if (names(dim(exp[[1]]))[1] == "lat" & names(dim(exp[[1]]))[2] == "lon" - || names(dim(exp[[1]]))[2] == "lat" & names(dim(exp[[1]]))[3] == "lon") { - texp2D <- lapply(exp, MergeDims, merge_dims = c('lat', 'lon'), - rename_dim = 'gridpoint') -} + if (names(dim(exp[[1]]))[1] == "lon" & names(dim(exp[[1]]))[2] == "lat" + || names(dim(exp[[1]]))[2] == "lon" & names(dim(exp[[1]]))[3] == "lat") { + texp2D <- lapply(exp, MergeDims, merge_dims = c('lon', 'lat'), + rename_dim = 'gridpoint') + } else if (names(dim(exp[[1]]))[1] == "lat" & names(dim(exp[[1]]))[2] == "lon" + || names(dim(exp[[1]]))[2] == "lat" & names(dim(exp[[1]]))[3] == "lon") { + texp2D <- lapply(exp, MergeDims, merge_dims = c('lat', 'lon'), + rename_dim = 'gridpoint') + } -if (names(dim(slp))[1] == "lon" & names(dim(slp))[2] == "lat" - || names(dim(slp))[2] == "lon" & names(dim(slp))[3] == "lat") { - tslp2D <- MergeDims(slp,merge_dims = c('lon', 'lat'), - rename_dim = 'gridpoint') -} else if (names(dim(slp))[1] == "lat" & names(dim(slp))[2] == "lon" - || names(dim(slp))[2] == "lat" & names(dim(slp))[3] == "lon") { - tslp2D <- MergeDims(slp,merge_dims = c('lat', 'lon'), - rename_dim = 'gridpoint') -} + if (names(dim(slp))[1] == "lon" & names(dim(slp))[2] == "lat" + || names(dim(slp))[2] == "lon" & names(dim(slp))[3] == "lat") { + tslp2D <- MergeDims(slp,merge_dims = c('lon', 'lat'), + rename_dim = 'gridpoint') + } else if (names(dim(slp))[1] == "lat" & names(dim(slp))[2] == "lon" + || names(dim(slp))[2] == "lat" & names(dim(slp))[3] == "lon") { + tslp2D <- MergeDims(slp,merge_dims = c('lat', 'lon'), + rename_dim = 'gridpoint') + } -if (names(dim(obs[[1]]))[1] == "lon" & names(dim(obs[[1]]))[2] == "lat" - || names(dim(obs[[1]]))[2] == "lon" & names(dim(obs[[1]]))[3] == "lat") { - tobs2D <- lapply(obs, MergeDims, merge_dims = c('lon', 'lat'), - rename_dim = 'gridpoint') -} else if (names(dim(obs[[1]]))[1] == "lat" & names(dim(obs[[1]]))[2] == "lon" - || names(dim(obs[[1]]))[2] == "lat" & names(dim(obs[[1]]))[3] == "lon") { - tobs2D <- lapply(obs, MergeDims, merge_dims = c('lat', 'lon'), - rename_dim = 'gridpoint') -} + if (names(dim(obs[[1]]))[1] == "lon" & names(dim(obs[[1]]))[2] == "lat" + || names(dim(obs[[1]]))[2] == "lon" & names(dim(obs[[1]]))[3] == "lat") { + tobs2D <- lapply(obs, MergeDims, merge_dims = c('lon', 'lat'), + rename_dim = 'gridpoint') + } else if (names(dim(obs[[1]]))[1] == "lat" & names(dim(obs[[1]]))[2] == "lon" + || names(dim(obs[[1]]))[2] == "lat" & names(dim(obs[[1]]))[3] == "lon") { + tobs2D <- lapply(obs, MergeDims, merge_dims = c('lat', 'lon'), + rename_dim = 'gridpoint') + } -if (names(dim(texp2D[[1]]))[1] == "gridpoint") { - exp2D <- lapply(texp2D,aperm) -} else { - exp2D <- texp2D -} + if (names(dim(texp2D[[1]]))[1] == "gridpoint") { + exp2D <- lapply(texp2D,aperm) + } else { + exp2D <- texp2D + } -if (names(dim(tslp2D))[1] == "gridpoint") { - slp2D <- aperm(tslp2D) -} else { - slp2D <- tslp2D -} + if (names(dim(tslp2D))[1] == "gridpoint") { + slp2D <- aperm(tslp2D) + } else { + slp2D <- tslp2D + } -if (names(dim(tobs2D[[1]]))[1] == "gridpoint") { - obs2D <- lapply(tobs2D,aperm) -} else { - obs2D <- tobs2D -} + if (names(dim(tobs2D[[1]]))[1] == "gridpoint") { + obs2D <- lapply(tobs2D,aperm) + } else { + obs2D <- tobs2D + } - downres <- .analogspred(exp2D, - slp2D, - obs2D, - lon, - lat, - slp_lon, - slp_lat, - var_name, - hr_obs, - tdates, - ddates, - restrain) + downres <- .analogspred(exp2D, slp2D, obs2D, lon, lat, slp_lon, slp_lat, + var_name, hr_obs, tdates, ddates, restrain) } #' Atomic .analogspred function #' #'@author Marta Dom\'inguez Alonso - AEMET, \email{mdomingueza@aemet.es} -#' -#' This function works with lists of matrix from reanalysis and seasonal -#' forecast data and uses a Fortran interface (.Fortran) to run an -#' analogs method developed in AEMET. +#'This function works with lists of matrix from reanalysis and seasonal +#'forecast data and uses a Fortran interface (.Fortran) to run an +#'analogs method developed in AEMET. #'@param pred_mod List of matrix with downscaled period seasonal forecast data. The list -#' has to contain model atmospheric variables (instantaneous 12h data) that must -#' be indentify by parenthesis name. -#' For precipitation: -#' - u component of wind at 500 hPa (u500_mod) in m/s -#' - v component of wind at 500 hPa (v500_mod) in m/s -#' - temperature at 500 hPa (t500_mod) in K -#' - temperature at 850 hPa (t850_mod) in K -#' - specific humidity at 700 hPa (q700_mod) in g/kg -#' For temperature: -#' - u component of wind at 500 hPa (u500_mod) in m/s -#' - v component of wind at 500 hPa (v500_mod) in m/s -#' - temperature at 500 hPa (t500_mod) in K -#' - temperature at 700 hPa (t500_mod) in K -#' - temperature at 850 hPa (t850_mod) in K -#' - specific humidity at 700 hPa (q700_mod) in g/kg -#' - 2 meters temperature (tm2m_mod) in K -#' Seasonal forecast variables must have the same resolution and -#' domain as 'pred_rea' parameter. -#' All matrices must have two dimensions with names 'time' and 'gridpoint'. -#'@param pred_slp Matrix with atmospheric seasonal forecast model sea level pressure -#' (instantaneous 12h data) that must be indentify as 'slp'. It has the same -#' resolution as 'pred_mod' paremeter but with an extended domain. This domain contains -#' extra degrees (most in the north and west part) compare to synoptic domain. -#' The matrix must have two dimensions with names 'time' and 'gridpoint'. -#'@param pred_rea List of matrix with training period reanalysis data. -#' The list has to contain reanalysis atmospheric variables (instantaneous -#' 12h data) that must be indentify by parenthesis name. -#' For precipitation: -#' - u component of wind at 500 hPa (u500) in m/s -#' - v component of wind at 500 hPa (v500) in m/s -#' - temperature at 500 hPa (t500) in K -#' - temperature at 850 hPa (t850) in K -#' - sea level pressure (slp) in hPa -#' - specific humidity at 700 hPa (q700) in g/kg -#' For maximum and minimum temperature: -#' - u component of wind at 500 hPa (u500) in m/s -#' - v component of wind at 500 hPa (v500) in m/s -#' - temperature at 500 hPa (t500) in K -#' - temperature at 700 hPa (t500) in K -#' - temperature at 850 hPa (t850) in K -#' - sea level pressure (slp) in hPa -#' - specific humidity at 700 hPa (q700) in g/kg -#' - 2 meters temperature (tm2m) in K -#' All matrices must have two dimensions with names 'ddates' and 'gridpoint'. +#' has to contain model atmospheric variables (instantaneous 12h data) that must +#' be indentify by parenthesis name. For precipitation: +#' \itemize{ +#' \item{u component of wind at 500 hPa (u500_mod) in m/s.} +#' \item{v component of wind at 500 hPa (v500_mod) in m/s.} +#' \item{temperature at 500 hPa (t500_mod) in K.} +#' \item{temperature at 850 hPa (t850_mod) in K.} +#' \item{specific humidity at 700 hPa (q700_mod) in g/kg.} +#' } +#' For temperature: +#' \itemize{ +#' \item{u component of wind at 500 hPa (u500_mod) in m/s.} +#' \item{v component of wind at 500 hPa (v500_mod) in m/s.} +#' \item{temperature at 500 hPa (t500_mod) in K.} +#' \item{temperature at 700 hPa (t500_mod) in K.} +#' \item{temperature at 850 hPa (t850_mod) in K.} +#' \item{specific humidity at 700 hPa (q700_mod) in g/kg.} +#' \item{2 meters temperature (tm2m_mod) in K.} +#' } +#' Seasonal forecast variables must have the same resolution and +#' domain as 'pred_rea' parameter. All matrices must have two dimensions with +#' names 'time' and 'gridpoint'. +#'@param pred_slp Matrix with atmospheric seasonal forecast model sea level +#' pressure (instantaneous 12h data) that must be indentify as 'slp'. It has +#' the same resolution as 'pred_mod' paremeter but with an extended domain. +#' This domain contains extra degrees (most in the north and west part) compare +#' to synoptic domain. The matrix must have two dimensions with names 'time' +#' and 'gridpoint'. +#'@param pred_rea List of matrix with training period reanalysis data. The +#' list has to contain reanalysis atmospheric variables (instantaneous 12h +#' data) that must be indentify by parenthesis name. For precipitation: +#' \itemize{ +#' \item{u component of wind at 500 hPa (u500) in m/s.} +#' \item{v component of wind at 500 hPa (v500) in m/s.} +#' \item{temperature at 500 hPa (t500) in K.} +#' \item{temperature at 850 hPa (t850) in K.} +#' \item{sea level pressure (slp) in hPa.} +#' \item{specific humidity at 700 hPa (q700) in g/kg.} +#' } +#' For maximum and minimum temperature: +#' \itemize{ +#' \item{u component of wind at 500 hPa (u500) in m/s.} +#' \item{v component of wind at 500 hPa (v500) in m/s.} +#' \item{temperature at 500 hPa (t500) in K.} +#' \item{temperature at 700 hPa (t500) in K.} +#' \item{temperature at 850 hPa (t850) in K.} +#' \item{sea level pressure (slp) in hPa.} +#' \item{specific humidity at 700 hPa (q700) in g/kg.} +#' \item{2 meters temperature (tm2m) in K} +#' } +#' All matrices must have two dimensions with names 'ddates' and 'gridpoint'. #'@param lon Vector of the synoptic longitude (from (-180º) to 180º), -#' The vector must go from west to east. -#'@param lat Vector of the synoptic latitude. The vector must go from north to south. +#' The vector must go from west to east. +#'@param lat Vector of the synoptic latitude. The vector must go from north to +#' south. #'@param slp_lon Vector of the extended longitude (from (-180º) to 180º), -#' The vector must go from west to east. -#'@param slp_lat Vector of the extended latitude. The vector must go from north to south. +#' The vector must go from west to east. +#'@param slp_lat Vector of the extended latitude. The vector must go from north +#' to south. #'@param var Variable name to downscale. There are two options: 'prec' for -#' precipitation and 'temp' for maximum and minimum temperature. +#' precipitation and 'temp' for maximum and minimum temperature. #'@param HR_path Local path of HR observational files (maestro and pcp/tmx-tmn). -#' For precipitation can be downloaded from http://www.aemet.es/documentos/es/serviciosclimaticos/cambio_climat/datos_diarios/dato_observacional/rejilla_5km/v2/Serie_AEMET_v2_pcp_1951a201903_txt.tar.gz -#' For maximum and minimum temperature can be downloaded from http://www.aemet.es/documentos/es/serviciosclimaticos/cambio_climat/datos_diarios/dato_observacional/rejilla_5km/temperatura/v1/tmax/Serie_AEMET_v1_tmax_1951a202006_txt.tar.gz and http://www.aemet.es/documentos/es/serviciosclimaticos/cambio_climat/datos_diarios/dato_observacional/rejilla_5km/temperatura/v1/tmin/Serie_AEMET_v1_tmin_1951a202006_txt.tar.gz respetively. -#' Maestro file (maestro_red_hr_SPAIN.txt) has gridpoint (nptos), longitude (lon), latitude (lat) and -#' altitude (alt) in columns (vector structure). -#' Data file (pcp/tmx/tmn_red_SPAIN_1951-201903.txt) includes 5km resolution spanish daily data -#' (precipitation or maximum and minimum temperature from january 1951 to march 2019. See README -#' file for more information. -#' IMPORTANT!: HR observational period must be the same as for reanalysis variables -#' ('pred_rea' parameter). -#' It is assumed that the training period is smaller than the HR original one (1951-2019), so it is -#' needed to make a new ascii file with the new period and the same structure as original, -#' specifying the training dates in the name (e.g. 'pcp_red_SPAIN_19810101-19961231.txt' for -#' '19810101-19961231' period). +#' For precipitation and temperature can be downloaded from the following link: +#' \url{https://www.aemet.es/en/serviciosclimaticos/cambio_climat/datos_diarios?w=2} +#' respetively. Maestro file (maestro_red_hr_SPAIN.txt) has gridpoint (nptos), +#' longitude (lon), latitude (lat) and altitude (alt) in columns (vector +#' structure). Data file (pcp/tmx/tmn_red_SPAIN_1951-201903.txt) includes 5km +#' resolution spanish daily data (precipitation or maximum and minimum +#' temperature from january 1951 to march 2019. See README file for more +#' information. IMPORTANT!: HR observational period must be the same as for +#' reanalysis variables ('pred_rea' parameter). It is assumed that the training +#' period is smaller than the HR original one (1951-2019), so it is needed to +#' make a new ascii file with the new period and the same structure as original, +#' specifying the training dates in the name (e.g. +#' 'pcp_red_SPAIN_19810101-19961231.txt' for '19810101-19961231' period). #'@param tdates Training period dates in format YYYYMMDD(start)-YYYYMMDD(end) -#' (e.g. 19810101-20181231). The same as for the training function. -#'@param ddates Downscaling period dates in format YYYYMMDD(start)-YYYYMMDD(end) (e.g. 20191001-20200331). -#'@param restrain Output (list of matrix) obtained from 'training_analogs' function. -#' For precipitation, 'restrain' object must contains um, vm, nger, gu92, gv92, -#' gu52, gv52, neni, vdmin, vref, ccm, lab_pred and cor_pred variables. -#' For maximum and minimum temperature, 'restrain' object must contains um, vm, -#' insol, neni, vdmin y vref. See 'AnalogsPred_train.R' for more information. -#'@return .analogspred returns seasonal forecast precipitation (mm) or -#' maximum and minimum temperature (dozens of ºC) in a 5km x 5km regular grid over -#' peninsular Spain and Balearic Islands. Each matrix of the list has two dimensions -#' ('ddates' x 'nptos'). +#' (e.g. 19810101-20181231). The same as for the training function. +#'@param ddates Downscaling period dates in format YYYYMMDD(start)-YYYYMMDD(end) +#' (e.g. 20191001-20200331). +#'@param restrain Output (list of matrix) obtained from 'training_analogs' +#' function. For precipitation, 'restrain' object must contains um, vm, nger, +#' gu92, gv92, gu52, gv52, neni, vdmin, vref, ccm, lab_pred and cor_pred +#' variables. For maximum and minimum temperature, 'restrain' object must +#' contains um, vm, insol, neni, vdmin y vref. See 'AnalogsPred_train.R' for +#' more information. +#'@return .analogspred Returns seasonal forecast precipitation (mm) or maximum +#'and minimum temperature (dozens of ºC) in a 5km x 5km regular grid over +#'peninsular Spain and Balearic Islands. Each matrix of the list has two +#'dimensions ('ddates' x 'nptos'). #' #'@importFrom utils read.table -#' #'@useDynLib CSTools #'@noRd +.analogspred <- function(pred_mod, pred_slp, pred_rea, lon, lat, slp_lon, + slp_lat, var, HR_path, tdates, ddates, restrain) { + if (!is.list(pred_mod)) { + stop("Parameter 'pred_mod' must be a list of 'matrix' objects") + } -.analogspred <- function(pred_mod, - pred_slp, - pred_rea, - lon, - lat, - slp_lon, - slp_lat, - var, - HR_path, - tdates, - ddates, - restrain) { + if (!(all(sapply(pred_mod, inherits, 'matrix')))) { + stop("Elements of the list in parameter 'pred_mod' must be of the class ", + "'matrix'.") + } + if (!is.matrix(pred_slp)) { + stop("Parameter 'pred_slp' must be of the class 'matrix'.") + } -if (!is.list(pred_mod)) { - stop("Parameter 'pred_mod' must be a list of 'matrix' objects") - } + if (!is.list(pred_rea)) { + stop("Parameter 'pred_rea' must be a list of 'matrix' objects") + } -if (!(all(sapply(pred_mod, inherits, 'matrix')))) { - stop("Elements of the list in parameter 'pred_mod' must be of the class ", - "'matrix'.") - } + if (!(all(sapply(pred_rea, inherits, 'matrix')))) { + stop("Elements of the list in parameter 'pred_rea' must be of the class ", + "'matrix'.") + } -if (!is.matrix(pred_slp)) { - stop("Parameter 'pred_slp' must be of the class 'matrix'.") + if (var == "prec") { + if (length(pred_rea) != 6) { + stop("Parameter 'pred_rea' must be a length of 6.") + } + if (length(pred_mod) != 5) { + stop("Parameter 'pred_mod' must be a length of 5.") + } + } else { + if (length(pred_rea) != 8) { + stop("Parameter 'pred_rea' must be a length of 8.") + } + if (length(pred_mod) != 7) { + stop("Parameter 'pred_mod' must be a length of 7.") + } } -if (!is.list(pred_rea)) { - stop("Parameter 'pred_rea' must be a list of 'matrix' objects") - } + if (!is.vector(lon) || !is.numeric(lon)) { + stop("Parameter 'lon' must be a numeric vector") + } -if (!(all(sapply(pred_rea, inherits, 'matrix')))) { - stop("Elements of the list in parameter 'pred_rea' must be of the class ", - "'matrix'.") - } + if (!is.vector(lat) || !is.numeric(lat)) { + stop("Parameter 'lat' must be a numeric vector") + } -if (var == "prec") { - if (length(pred_rea) != 6) { - stop("Parameter 'pred_rea' must be a length of 6.") - } - if (length(pred_mod) != 5) { - stop("Parameter 'pred_mod' must be a length of 5.") - } -} else { - if (length(pred_rea) != 8) { - stop("Parameter 'pred_rea' must be a length of 8.") - } - if (length(pred_mod) != 7) { - stop("Parameter 'pred_mod' must be a length of 7.") - } -} + if (!is.vector(slp_lon) || !is.numeric(slp_lon)) { + stop("Parameter 'slp_lon' must be a numeric vector") + } -if (!is.vector(lon) || !is.numeric(lon)) { - stop("Parameter 'lon' must be a numeric vector") - } + if (!is.vector(slp_lat) || !is.numeric(slp_lat)) { + stop("Parameter 'slp_lat' must be a numeric vector") + } -if (!is.vector(lat) || !is.numeric(lat)) { - stop("Parameter 'lat' must be a numeric vector") - } + if (!is.character(HR_path)){ + stop("Parameter 'HR_path' must be a character.") + } -if (!is.vector(slp_lon) || !is.numeric(slp_lon)) { - stop("Parameter 'slp_lon' must be a numeric vector") - } + if (!is.character(tdates)) { + stop("Parameter 'tdates' must be a character.") + } -if (!is.vector(slp_lat) || !is.numeric(slp_lat)) { - stop("Parameter 'slp_lat' must be a numeric vector") - } + if (!is.character(ddates)) { + stop("Parameter 'ddates' must be a character.") + } -if (!is.character(HR_path)){ - stop("Parameter 'HR_path' must be a character.") - } + if (!is.list(restrain)) { + stop("Parameter 'restrain' must be a list of 'matrix' and 'parameter' objects") + } -if (!is.character(tdates)) { - stop("Parameter 'tdates' must be a character.") - } + #! REANALYSIS GRID PARAMETERS -if (!is.character(ddates)) { - stop("Parameter 'ddates' must be a character.") - } + rlon <- c(lon, NA) - c(NA, lon) + rlon <- rlon[!is.na(rlon)] + if (!all(rlon == rlon[1])) { + stop("Parameter 'lon' must be in regular grid.") + } else { + rlon <- rlon[1] + } -if (!is.list(restrain)) { - stop("Parameter 'restrain' must be a list of 'matrix' and 'parameter' objects") - } + rlat <- c(lat, NA) - c(NA, lat) + rlat <- rlat[!is.na(rlat)] + if (!all(rlat == rlat[1])) { + stop("Parameter 'lat' must be in regular grid.") + } else { + rlat <- rlat[1] + } -#! REANALYSIS GRID PARAMETERS + if (rlon != (-rlat)) { + stop("Parameters 'lon' and 'lat' must have the same resolution.") + } else { + res <- rlon + } - rlon <- c(lon, NA) - c(NA, lon) - rlon <- rlon[!is.na(rlon)] - if (!all(rlon == rlon[1])) { - stop("Parameter 'lon' must be in regular grid.") - } else { - rlon <- rlon[1] - } + nlat <- ((lat[length(lat)] - lat[1]) / rlat) + 1 + nlon <- ((lon[length(lon)] - lon[1]) / rlon) + 1 + + ic <- nlat * nlon + # + slp_rlon <- c(slp_lon, NA) - c(NA, slp_lon) + slp_rlon <- slp_rlon[!is.na(slp_rlon)] + if (!all(slp_rlon == slp_rlon[1])) { + stop("Parameter 'slp_lon' must be in regular grid.") + } else { + slp_rlon <- slp_rlon[1] + } - rlat <- c(lat, NA) - c(NA, lat) - rlat <- rlat[!is.na(rlat)] - if (!all(rlat == rlat[1])) { - stop("Parameter 'lat' must be in regular grid.") - } else { - rlat <- rlat[1] - } + slp_rlat <- c(slp_lat, NA) - c(NA, slp_lat) + slp_rlat <- slp_rlat[!is.na(slp_rlat)] + if (!all(slp_rlat == slp_rlat[1])) { + stop("Parameter 'slp_lat' must be in regular grid.") + } else { + slp_rlat <- slp_rlat[1] + } - if (rlon != (-rlat)) { - stop("Parameters 'lon' and 'lat' must have the same resolution.") - } else { - res <- rlon - } + if (slp_rlon != (-slp_rlat)) { + stop("Parameters 'slp_lon' and 'slp_lat' must have the same resolution.") + } else { + slp_res <- slp_rlon + } - nlat <- ((lat[length(lat)] - lat[1]) / rlat) + 1 - nlon <- ((lon[length(lon)] - lon[1]) / rlon) + 1 + nlatt <- ((slp_lat[length(slp_lat)] - slp_lat[1]) / slp_rlat) + 1 + nlont <- ((slp_lon[length(slp_lon)] - slp_lon[1]) / slp_rlon) + 1 - ic <- nlat * nlon -# - slp_rlon <- c(slp_lon, NA) - c(NA, slp_lon) - slp_rlon <- slp_rlon[!is.na(slp_rlon)] - if (!all(slp_rlon == slp_rlon[1])) { - stop("Parameter 'slp_lon' must be in regular grid.") - } else { - slp_rlon <- slp_rlon[1] - } + id <- nlatt * nlont - slp_rlat <- c(slp_lat, NA) - c(NA, slp_lat) - slp_rlat <- slp_rlat[!is.na(slp_rlat)] - if (!all(slp_rlat == slp_rlat[1])) { - stop("Parameter 'slp_lat' must be in regular grid.") - } else { - slp_rlat <- slp_rlat[1] - } + slat <- max(lat) + slon <- min(c(lon[which(lon > 180)] - 360, + lon[which(lon <= 180)])) - if (slp_rlon != (-slp_rlat)) { - stop("Parameters 'slp_lon' and 'slp_lat' must have the same resolution.") - } else { - slp_res <- slp_rlon - } + slatt <- max(slp_lat) + slont <- min(c(slp_lon[which(slp_lon > 180)] - 360, + slp_lon[which(slp_lon <= 180)])) - nlatt <- ((slp_lat[length(slp_lat)] - slp_lat[1]) / slp_rlat) + 1 - nlont <- ((slp_lon[length(slp_lon)] - slp_lon[1]) / slp_rlon) + 1 + ngridd <- ((2*nlatt)-1)*((2*nlont)-1) - id <- nlatt * nlont + if (all((sapply(pred_rea,nrow))==nrow(pred_rea[[1]]))){ + nd <- nrow(pred_rea[[1]]) + } else { + stop("All 'pred_rea' variables must have the same period.") + } - slat <- max(lat) - slon <- min(c(lon[which(lon > 180)] - 360, - lon[which(lon <= 180)])) + if (all((sapply(pred_mod,nrow))==nrow(pred_mod[[1]]))){ + nm <- nrow(pred_mod[[1]]) + } else { + stop("All 'pred_mod' variables must have the same period.") + } - slatt <- max(slp_lat) - slont <- min(c(slp_lon[which(slp_lon > 180)] - 360, - slp_lon[which(slp_lon <= 180)])) + seqdates <- seq(as.Date(substr(ddates,start=1,stop=8),format="%Y%m%d"),as.Date(substr(ddates,start=10,stop=18),format="%Y%m%d"),by="days") + month <- format(seqdates,format="%m") + day <- format(seqdates,format="%d") + + #! TRAINING REANALYSIS VARIABLES + u500 <- pred_rea[['u500']] + v500 <- pred_rea[['v500']] + t500 <- pred_rea[['t500']] + t850 <- pred_rea[['t850']] + msl_si <- pred_rea[['slp']] + q700 <- pred_rea[['q700']] + + if (var == "temp") { + t700 <- pred_rea[['t700']] + tm2m <- pred_rea[['tm2m']] + } - ngridd <- ((2*nlatt)-1)*((2*nlont)-1) + #! SEASONAL FORECAST MODEL VARIABLES + u500_mod <- pred_mod[['u500_mod']] + v500_mod <- pred_mod[['v500_mod']] + t500_mod <- pred_mod[['t500_mod']] + t850_mod <- pred_mod[['t850_mod']] + msl_lr_mod <- pred_slp + q700_mod <- pred_mod[['q700_mod']] + + if (var == "temp") { + t700_mod <- pred_mod[['t700_mod']] + tm2m_mod <- pred_mod[['tm2m_mod']] + } - if (all((sapply(pred_rea,nrow))==nrow(pred_rea[[1]]))){ - nd <- nrow(pred_rea[[1]]) + #! HIGH-RESOLUTION (HR) OBSERVATIONAL DATASET + maestro_hr_file <- paste(HR_path, "maestro_red_hr_SPAIN.txt",sep="") + if (!file.exists(maestro_hr_file)) { + stop("'maestro_red_hr_SPAIN.txt' does not exist.") } else { - stop("All 'pred_rea' variables must have the same period.") + maestro <- read.table(maestro_hr_file) + lon_hr <- unlist(maestro[2]) + lat_hr <- unlist(maestro[3]) + nptos <- length(readLines(maestro_hr_file)) } - if (all((sapply(pred_mod,nrow))==nrow(pred_mod[[1]]))){ - nm <- nrow(pred_mod[[1]]) + if (var == "prec") { + prec_hr_file <- paste(HR_path, "pcp_red_SPAIN_",tdates,".txt",sep="") + if (!file.exists(prec_hr_file)) { + stop(sprintf("precipitation HR file for %s does not exist.",tdates)) + } else { + nd_hr <- length(readLines(prec_hr_file)) + preprec_hr <- matrix(scan(prec_hr_file), nrow=nd_hr ,ncol= nptos+1, byrow=TRUE) + prec_hr <- preprec_hr[1:nd_hr,-c(1)] + } } else { - stop("All 'pred_mod' variables must have the same period.") + tmx_hr_file <- paste(HR_path, "tmx_red_SPAIN_",tdates,".txt",sep="") + tmn_hr_file <- paste(HR_path, "tmn_red_SPAIN_",tdates,".txt",sep="") + if (!file.exists(tmx_hr_file)) { + stop(sprintf("maximum temperature HR file for %s does not exist.",tdates)) + } else if (!file.exists(tmn_hr_file)) { + stop(sprintf("minimum temperature HR file for %s does not exist.",tdates)) + } else if (length(readLines(tmx_hr_file)) != length(readLines(tmn_hr_file))) { + stop("maximum and minimum temperature HR observation files must have the same period.") + } else { + nd_hr <- length(readLines(tmx_hr_file)) + pretmx_hr <- matrix(scan(tmx_hr_file), nrow=nd_hr ,ncol= nptos+1, byrow=TRUE) + tmx_hr <- pretmx_hr[1:nd_hr,-c(1)] + pretmn_hr <- matrix(scan(tmn_hr_file), nrow=nd_hr ,ncol= nptos+1, byrow=TRUE) + tmn_hr <- pretmn_hr[1:nd_hr,-c(1)] + } } - seqdates <- seq(as.Date(substr(ddates,start=1,stop=8),format="%Y%m%d"),as.Date(substr(ddates,start=10,stop=18),format="%Y%m%d"),by="days") - month <- format(seqdates,format="%m") - day <- format(seqdates,format="%d") - -#! TRAINING REANALYSIS VARIABLES -u500 <- pred_rea[['u500']] -v500 <- pred_rea[['v500']] -t500 <- pred_rea[['t500']] -t850 <- pred_rea[['t850']] -msl_si <- pred_rea[['slp']] -q700 <- pred_rea[['q700']] - -if (var == "temp") { -t700 <- pred_rea[['t700']] -tm2m <- pred_rea[['tm2m']] -} - -#! SEASONAL FORECAST MODEL VARIABLES -u500_mod <- pred_mod[['u500_mod']] -v500_mod <- pred_mod[['v500_mod']] -t500_mod <- pred_mod[['t500_mod']] -t850_mod <- pred_mod[['t850_mod']] -msl_lr_mod <- pred_slp -q700_mod <- pred_mod[['q700_mod']] - -if (var == "temp") { -t700_mod <- pred_mod[['t700_mod']] -tm2m_mod <- pred_mod[['tm2m_mod']] -} - -#! HIGH-RESOLUTION (HR) OBSERVATIONAL DATASET -maestro_hr_file <- paste(HR_path, "maestro_red_hr_SPAIN.txt",sep="") -if (!file.exists(maestro_hr_file)) { - stop("'maestro_red_hr_SPAIN.txt' does not exist.") -} else { - maestro <- read.table(maestro_hr_file) - lon_hr <- unlist(maestro[2]) - lat_hr <- unlist(maestro[3]) - nptos <- length(readLines(maestro_hr_file)) -} + if (nd_hr != nd) { + stop("Reanalysis variables and HR observations must have the same period.") + } -if (var == "prec") { - prec_hr_file <- paste(HR_path, "pcp_red_SPAIN_",tdates,".txt",sep="") - if (!file.exists(prec_hr_file)) { - stop(sprintf("precipitation HR file for %s does not exist.",tdates)) - } else { - nd_hr <- length(readLines(prec_hr_file)) - preprec_hr <- matrix(scan(prec_hr_file), nrow=nd_hr ,ncol= nptos+1, byrow=TRUE) - prec_hr <- preprec_hr[1:nd_hr,-c(1)] - } -} else { - tmx_hr_file <- paste(HR_path, "tmx_red_SPAIN_",tdates,".txt",sep="") - tmn_hr_file <- paste(HR_path, "tmn_red_SPAIN_",tdates,".txt",sep="") - if (!file.exists(tmx_hr_file)) { - stop(sprintf("maximum temperature HR file for %s does not exist.",tdates)) - } else if (!file.exists(tmn_hr_file)) { - stop(sprintf("minimum temperature HR file for %s does not exist.",tdates)) - } else if (length(readLines(tmx_hr_file)) != length(readLines(tmn_hr_file))) { - stop("maximum and minimum temperature HR observation files must have the same period.") - } else { - nd_hr <- length(readLines(tmx_hr_file)) - pretmx_hr <- matrix(scan(tmx_hr_file), nrow=nd_hr ,ncol= nptos+1, byrow=TRUE) - tmx_hr <- pretmx_hr[1:nd_hr,-c(1)] - pretmn_hr <- matrix(scan(tmn_hr_file), nrow=nd_hr ,ncol= nptos+1, byrow=TRUE) - tmn_hr <- pretmn_hr[1:nd_hr,-c(1)] - } -} + #! OTHER PARAMETERS that should not be changed + #! Number of analog situations to consider + nanx <- 155 + #! Number of temperature predictors + nvar <- 7 + + #!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + if (var == "prec") { + + downs <- .Fortran("down_prec", + ic = as.integer(ic), + id = as.integer(id), + nd = as.integer(nd), + nm = as.integer(nm), + nlat = as.integer(nlat), + nlon = as.integer(nlon), + nlatt = as.integer(nlatt), + nlont = as.integer(nlont), + slat = as.numeric(slat), + slon = as.numeric(slon), + rlat = as.numeric(rlat), + rlon = as.numeric(rlon), + slatt = as.numeric(slatt), + slont = as.numeric(slont), + ngridd = as.integer(ngridd), + u500 = as.numeric(u500), + v500 = as.numeric(v500), + t500 = as.numeric(t500), + t850 = as.numeric(t850), + msl_si = as.numeric(msl_si), + q700 = as.numeric(q700), + prec_hr = as.numeric(prec_hr), + nanx = as.integer(nanx), + restrain$um, + restrain$vm, + restrain$nger, + restrain$gu92, + restrain$gv92, + restrain$gu52, + restrain$gv52, + restrain$neni, + restrain$vdmin, + restrain$vref, + restrain$ccm, + restrain$indices[,,,1],#lab_pred + restrain$indices[,,,2],#cor_pred + u500_mod = as.numeric(u500_mod), + v500_mod = as.numeric(v500_mod), + t500_mod = as.numeric(t500_mod), + t850_mod = as.numeric(t850_mod), + msl_lr_mod = as.numeric(msl_lr_mod), + q700_mod = as.numeric(q700_mod), + pp=matrix(as.double(seq(1,nm*nptos)),c(nm,nptos)), + PACKAGE = 'CSTools') + + output <- downs$pp - if (nd_hr != nd) { - stop("Reanalysis variables and HR observations must have the same period.") - } + } else { -#! OTHER PARAMETERS that should not be changed -#! Number of analog situations to consider -nanx <- 155 -#! Number of temperature predictors -nvar <- 7 - -#!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -if (var == "prec") { - - downs <- .Fortran("down_prec", - ic = as.integer(ic), - id = as.integer(id), - nd = as.integer(nd), - nm = as.integer(nm), - nlat = as.integer(nlat), - nlon = as.integer(nlon), - nlatt = as.integer(nlatt), - nlont = as.integer(nlont), - slat = as.numeric(slat), - slon = as.numeric(slon), - rlat = as.numeric(rlat), - rlon = as.numeric(rlon), - slatt = as.numeric(slatt), - slont = as.numeric(slont), - ngridd = as.integer(ngridd), - u500 = as.numeric(u500), - v500 = as.numeric(v500), - t500 = as.numeric(t500), - t850 = as.numeric(t850), - msl_si = as.numeric(msl_si), - q700 = as.numeric(q700), - prec_hr = as.numeric(prec_hr), - nanx = as.integer(nanx), - restrain$um, - restrain$vm, - restrain$nger, - restrain$gu92, - restrain$gv92, - restrain$gu52, - restrain$gv52, - restrain$neni, - restrain$vdmin, - restrain$vref, - restrain$ccm, - restrain$indices[,,,1],#lab_pred - restrain$indices[,,,2],#cor_pred - u500_mod = as.numeric(u500_mod), - v500_mod = as.numeric(v500_mod), - t500_mod = as.numeric(t500_mod), - t850_mod = as.numeric(t850_mod), - msl_lr_mod = as.numeric(msl_lr_mod), - q700_mod = as.numeric(q700_mod), - pp=matrix(as.double(seq(1,nm*nptos)),c(nm,nptos)), - PACKAGE = 'CSTools') - - output <- downs$pp - -} else { - - downs <- .Fortran("down_temp", - ic = as.integer(ic), - id = as.integer(id), - nd = as.integer(nd), - nm = as.integer(nm), - nlat = as.integer(nlat), - nlon = as.integer(nlon), - nlatt = as.integer(nlatt), - nlont = as.integer(nlont), - slat = as.numeric(slat), - slon = as.numeric(slon), - rlat = as.numeric(rlat), - rlon = as.numeric(rlon), - slatt = as.numeric(slatt), - slont = as.numeric(slont), - ngridd = as.integer(ngridd), - u500 = as.numeric(u500), - v500 = as.numeric(v500), - t500 = as.numeric(t500), - t850 = as.numeric(t850), - msl_si = as.numeric(msl_si), - q700 = as.numeric(q700), - t700 = as.numeric(t700), - tm2m = as.numeric(tm2m), - tmx_hr = as.numeric(tmx_hr), - tmn_hr = as.numeric(tmn_hr), - nanx = as.integer(nanx), - nvar = as.integer(nvar), - day = as.integer(day), - month = as.integer(month), - restrain$um, - restrain$vm, - restrain$insol, - restrain$neni, - restrain$vdmin, - restrain$vref, - u500_mod = as.numeric(u500_mod), - v500_mod = as.numeric(v500_mod), - t500_mod = as.numeric(t500_mod), - t850_mod = as.numeric(t850_mod), - msl_lr_mod = as.numeric(msl_lr_mod), - q700_mod = as.numeric(q700_mod), - t700_mod = as.numeric(t700_mod), - tm2m_mod = as.numeric(tm2m_mod), - tmx=matrix(as.double(seq(1,nm*nptos)),c(nm,nptos)), - tmn=matrix(as.double(seq(1,nm*nptos)),c(nm,nptos)), - PACKAGE = 'CSTools') - - output <- list("tmax" = downs$tmx, - "tmin" = downs$tmn) + downs <- .Fortran("down_temp", + ic = as.integer(ic), + id = as.integer(id), + nd = as.integer(nd), + nm = as.integer(nm), + nlat = as.integer(nlat), + nlon = as.integer(nlon), + nlatt = as.integer(nlatt), + nlont = as.integer(nlont), + slat = as.numeric(slat), + slon = as.numeric(slon), + rlat = as.numeric(rlat), + rlon = as.numeric(rlon), + slatt = as.numeric(slatt), + slont = as.numeric(slont), + ngridd = as.integer(ngridd), + u500 = as.numeric(u500), + v500 = as.numeric(v500), + t500 = as.numeric(t500), + t850 = as.numeric(t850), + msl_si = as.numeric(msl_si), + q700 = as.numeric(q700), + t700 = as.numeric(t700), + tm2m = as.numeric(tm2m), + tmx_hr = as.numeric(tmx_hr), + tmn_hr = as.numeric(tmn_hr), + nanx = as.integer(nanx), + nvar = as.integer(nvar), + day = as.integer(day), + month = as.integer(month), + restrain$um, + restrain$vm, + restrain$insol, + restrain$neni, + restrain$vdmin, + restrain$vref, + u500_mod = as.numeric(u500_mod), + v500_mod = as.numeric(v500_mod), + t500_mod = as.numeric(t500_mod), + t850_mod = as.numeric(t850_mod), + msl_lr_mod = as.numeric(msl_lr_mod), + q700_mod = as.numeric(q700_mod), + t700_mod = as.numeric(t700_mod), + tm2m_mod = as.numeric(tm2m_mod), + tmx=matrix(as.double(seq(1,nm*nptos)),c(nm,nptos)), + tmn=matrix(as.double(seq(1,nm*nptos)),c(nm,nptos)), + PACKAGE = 'CSTools') + + output <- list("tmax" = downs$tmx, + "tmin" = downs$tmn) } return(output) diff --git a/R/CST_Anomaly.R b/R/CST_Anomaly.R index a84b6fc8538b03f4113b96aa8b3126189a0bdee9..280104089729b7728f004fd332d22b1570caa702 100644 --- a/R/CST_Anomaly.R +++ b/R/CST_Anomaly.R @@ -53,12 +53,7 @@ #'attr(exp, 'class') <- 's2dv_cube' #'attr(obs, 'class') <- 's2dv_cube' #' -#'anom1 <- CST_Anomaly(exp = exp, obs = obs, cross = FALSE, memb = TRUE) -#'anom2 <- CST_Anomaly(exp = exp, obs = obs, cross = TRUE, memb = TRUE) -#'anom3 <- CST_Anomaly(exp = exp, obs = obs, cross = TRUE, memb = FALSE) -#'anom4 <- CST_Anomaly(exp = exp, obs = obs, cross = FALSE, memb = FALSE) -#'anom5 <- CST_Anomaly(lonlat_temp$exp) -#'anom6 <- CST_Anomaly(obs = lonlat_temp$obs) +#'anom <- CST_Anomaly(exp = exp, obs = obs, cross = FALSE, memb = TRUE) #' #'@seealso \code{\link[s2dv]{Ano_CrossValid}}, \code{\link[s2dv]{Clim}} and \code{\link{CST_Load}} #' diff --git a/R/CST_BEI_Weighting.R b/R/CST_BEI_Weighting.R index de7470110c4f9d090bc1ad84b6c786448a5c63c4..16c0b5d1bf49d0f54e145692a4b9e4a1ec9de98b 100644 --- a/R/CST_BEI_Weighting.R +++ b/R/CST_BEI_Weighting.R @@ -1,66 +1,65 @@ #' Weighting SFSs of a CSTools object. #' -#' @author Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} +#'@author Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} #' -#' @description Function to apply weights to a 's2dv_cube' object. -#' It could return a weighted ensemble mean (deterministic output) or -#' the terciles probabilities (probabilistic output) for Seasonal Forecast -#' Systems (SFSs). +#'@description Function to apply weights to a 's2dv_cube' object. +#'It could return a weighted ensemble mean (deterministic output) or +#'the terciles probabilities (probabilistic output) for Seasonal Forecast +#'Systems (SFSs). #' -#' @references Regionally improved seasonal forecast of precipitation through -#' Best estimation of winter NAO, Sanchez-Garcia, E. et al., -#' Adv. Sci. Res., 16, 165174, 2019, https://doi.org/10.5194/asr-16-165-2019 +#'@references Regionally improved seasonal forecast of precipitation through +#'Best estimation of winter NAO, Sanchez-Garcia, E. et al., +#'Adv. Sci. Res., 16, 165174, 2019, \url{https://doi.org/10.5194/asr-16-165-2019} #' -#' @param var_exp An object of the class 's2dv_cube' containing the variable -#' (e.g. precipitation, temperature, NAO index) array. -#' The var_exp object is expected to have an element named \code{$data} with -#' at least a temporal dimension and a dimension named 'member'. -#' @param aweights Normalized weights array with at least dimensions -#' (time, member), when 'time' is the temporal dimension as default. -#' When 'aweights' parameter has any other dimensions (as e.g. 'lat') and -#' 'var_exp' parameter has also the same dimension, they must be equals. -#' @param terciles A numeric array with at least one dimension 'tercil' equal to -#' 2, the first element is the lower tercil for a hindcast period, and the second -#' element is the upper tercile. By default is NULL, the terciles are computed -#' from var_exp data. -#' @param type A character string indicating the type of output. -#' If 'type' = 'probs', the function returns, in the element data from -#' 'var_exp' parameter, an array with at least two -#' or four dimensions depending if the variable is spatially aggregated variable -#' (as e.g. NAO index), dimension (time, tercil) or it is spatial variable -#' (as e.g. precipitation or temperature), dimension (time, tercile, lat, lon), -#' containing the terciles probabilities computing with weighted members. -#' The first tercil is the lower tercile, the second is the normal tercile and -#' the third is the upper tercile. -#' If 'type' = 'ensembleMean', the function returns, in the element data from -#' 'var_exp' parameter, an array with at least one or three dimensions -#' depending if the variable is a spatially aggregated variable -#' (as e.g. NAO index)(time) or it is spatial variable (as e.g. precipitation -#' or temperature) (time, lat, lon), containing the ensemble means computing -#' with weighted members. -#' @param time_dim_name A character string indicating the name of the +#'@param var_exp An object of the class 's2dv_cube' containing the variable +#' (e.g. precipitation, temperature, NAO index) array. +#' The var_exp object is expected to have an element named \code{$data} with +#' at least a temporal dimension and a dimension named 'member'. +#'@param aweights Normalized weights array with at least dimensions +#' (time, member), when 'time' is the temporal dimension as default. +#' When 'aweights' parameter has any other dimensions (as e.g. 'lat') and +#' 'var_exp' parameter has also the same dimension, they must be equals. +#'@param terciles A numeric array with at least one dimension 'tercil' equal to +#' 2, the first element is the lower tercil for a hindcast period, and the second +#' element is the upper tercile. By default is NULL, the terciles are computed +#' from var_exp data. +#'@param type A character string indicating the type of output. +#' If 'type' = 'probs', the function returns, in the element data from +#' 'var_exp' parameter, an array with at least two +#' or four dimensions depending if the variable is spatially aggregated variable +#' (as e.g. NAO index), dimension (time, tercil) or it is spatial variable +#' (as e.g. precipitation or temperature), dimension (time, tercile, lat, lon), +#' containing the terciles probabilities computing with weighted members. +#' The first tercil is the lower tercile, the second is the normal tercile and +#' the third is the upper tercile. If 'type' = 'ensembleMean', the function +#' returns, in the element data from 'var_exp' parameter, an array with at +#' least one or three dimensions depending if the variable is a spatially +#' aggregated variable (as e.g. NAO index)(time) or it is spatial variable (as +#' e.g. precipitation or temperature) (time, lat, lon), containing the ensemble +#' means computing with weighted members. +#'@param time_dim_name A character string indicating the name of the #' temporal dimension, by default 'time'. #' -#' @return CST_BEI_Weighting() returns a CSTools object (i.e., of the -#' class 's2dv_cube'). -#' This object has at least an element named \code{$data} -#' with at least a temporal dimension (and dimension 'tercil' when the output -#' are tercile probabilities), containing the ensemble means computing with -#' weighted members or probabilities of terciles. +#'@return CST_BEI_Weighting() returns a CSTools object (i.e., of the +#'class 's2dv_cube'). +#'This object has at least an element named \code{$data} +#'with at least a temporal dimension (and dimension 'tercil' when the output +#'are tercile probabilities), containing the ensemble means computing with +#'weighted members or probabilities of terciles. #' -#' @examples -#' var_exp <- 1 : (2 * 4 * 3 * 2) -#' dim(var_exp) <- c(time = 2, member = 4, lat = 3, lon = 2) -#' aweights <- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3, 0.1, 0.2, 0.4, 0.4, 0.1, 0.2, 0.4, 0.2) -#' dim(aweights) <- c(time = 2, member = 4, dataset = 2) -#' var_exp <- list(data = var_exp) -#' class(var_exp) <- 's2dv_cube' -#' res_CST <- CST_BEI_Weighting(var_exp, aweights) -#' dim(res_CST$data) -#' # time lat lon dataset -#' # 2 3 2 2 -#' @export - +#'@examples +#'var_exp <- 1 : (2 * 4 * 3 * 2) +#'dim(var_exp) <- c(time = 2, member = 4, lat = 3, lon = 2) +#'aweights <- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3, 0.1, 0.2, 0.4, 0.4, 0.1, +#' 0.2, 0.4, 0.2) +#'dim(aweights) <- c(time = 2, member = 4, dataset = 2) +#'var_exp <- list(data = var_exp) +#'class(var_exp) <- 's2dv_cube' +#'res_CST <- CST_BEI_Weighting(var_exp, aweights) +#'dim(res_CST$data) +#'# time lat lon dataset +#'# 2 3 2 2 +#'@export CST_BEI_Weighting <- function(var_exp, aweights, terciles = NULL, type = 'ensembleMean', time_dim_name = 'time') { @@ -155,52 +154,52 @@ CST_BEI_Weighting <- function(var_exp, aweights, terciles = NULL, } -#' @title Computing the weighted ensemble means for SFSs. -#' @author Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} -#' @description This function implements the computation to obtain the weighted -#' ensemble means for SFSs using a normalized weights array, +#'@title Computing the weighted ensemble means for SFSs. +#'@author Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} +#'@description This function implements the computation to obtain the weighted +#'ensemble means for SFSs using a normalized weights array, #' -#' @references Regionally improved seasonal forecast of precipitation through Best -#' estimation of winter NAO, Sanchez-Garcia, E. et al., -#' Adv. Sci. Res., 16, 165174, 2019, https://doi.org/10.5194/asr-16-165-2019 +#'@references Regionally improved seasonal forecast of precipitation through Best +#'estimation of winter NAO, Sanchez-Garcia, E. et al., +#'Adv. Sci. Res., 16, 165174, 2019, https://doi.org/10.5194/asr-16-165-2019 #' -#' @param var_exp Variable (e.g. precipitation, temperature, NAO index) -#' array from a SFS with at least dimensions (time, member) for a spatially -#' aggregated variable or dimensions (time, member, lat, lon) for a spatial -#' variable, as 'time' the spatial dimension by default. -#' @param aweights Normalized weights array with at least dimensions -#' (time, member), when 'time' is the temporal dimension as default. -#' @param time_dim_name A character string indicating the name of the -#' temporal dimension, by default 'time'. +#'@param var_exp Variable (e.g. precipitation, temperature, NAO index) +#' array from a SFS with at least dimensions (time, member) for a spatially +#' aggregated variable or dimensions (time, member, lat, lon) for a spatial +#' variable, as 'time' the spatial dimension by default. +#'@param aweights Normalized weights array with at least dimensions +#' (time, member), when 'time' is the temporal dimension as default. +#'@param time_dim_name A character string indicating the name of the +#' temporal dimension, by default 'time'. #' -#' @return BEI_EMWeighting() returns an array with at least one or three -#' dimensions depending if the variable is spatially aggregated variable -#' (as e.g. NAO index)(time) or it is spatial variable (as e.g. precipitation -#' or temperature) (time, lat, lon), containing the ensemble means computing -#' with weighted members. -#' @import multiApply +#'@return BEI_EMWeighting() returns an array with at least one or three +#'dimensions depending if the variable is spatially aggregated variable +#'(as e.g. NAO index)(time) or it is spatial variable (as e.g. precipitation +#'or temperature) (time, lat, lon), containing the ensemble means computing +#'with weighted members. +#'@import multiApply #' -#' @examples -#' # Example 1 -#' var_exp <- 1 : (2 * 3 * 4) -#' dim(var_exp) <- c(time = 2, dataset = 3, member = 4) -#' aweights<- runif(24, min=0.001, max=0.999) -#' dim(aweights) <- c(time = 2, dataset = 3, member = 4) -#' res <- BEI_EMWeighting(var_exp, aweights) -#' dim(res) -#' # time dataset -#' # 2 3 -#' # Example 2 -#' var_exp <- 1 : (2 * 4 * 2 * 3) -#' dim(var_exp) <- c(time = 2, member = 4, lat = 2, lon = 3) -#' aweights<- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3) -#' dim(aweights) <- c(time = 2, member = 4) -#' res <- BEI_EMWeighting(var_exp, aweights) -#' dim(res) -#' # time lat lon -#' # 2 2 3 +#'@examples +#'# Example 1 +#'var_exp <- 1 : (2 * 3 * 4) +#'dim(var_exp) <- c(time = 2, dataset = 3, member = 4) +#'aweights<- runif(24, min=0.001, max=0.999) +#'dim(aweights) <- c(time = 2, dataset = 3, member = 4) +#'res <- BEI_EMWeighting(var_exp, aweights) +#'dim(res) +#'# time dataset +#'# 2 3 +#'# Example 2 +#'var_exp <- 1 : (2 * 4 * 2 * 3) +#'dim(var_exp) <- c(time = 2, member = 4, lat = 2, lon = 3) +#'aweights<- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3) +#'dim(aweights) <- c(time = 2, member = 4) +#'res <- BEI_EMWeighting(var_exp, aweights) +#'dim(res) +#'# time lat lon +#'# 2 2 3 #' -#' @noRd +#'@noRd BEI_EMWeighting <- function(var_exp, aweights, time_dim_name = 'time') { if (!is.character(time_dim_name)) { stop("Parameter 'time_dim_name' must be a character string indicating", @@ -249,27 +248,27 @@ BEI_EMWeighting <- function(var_exp, aweights, time_dim_name = 'time') { return(res) } -#' Atomic BEI_EMWeighting -#' @param var_exp Variable (e.g. precipitation, temperature, NAO index) -#' array from a SFS with a temporal dimension, -#' by default 'time', and dimension 'member'. -#' @param aweights Normalized weights array with a temporal dimension, -#' by default 'time', and dimension 'member' -#' @param time_dim_name A character string indicating the name of the -#' temporal dimension, by default 'time'. -#' @return .BEI_EMWeighting returns an array of with a temporal dimension, -#' by default 'time', containing the weighted ensemble means. -#' @examples -#' # Example for the Atomic BEI_EMWeighting function -#' var_exp <- 1 : 6 -#' dim(var_exp) <- c(time = 2, member = 3) -#' aweights <- c(0.28, 0.15, 0.69, 0.64, 0.42, 0.17) -#' dim(aweights) <- c(time = 2, member = 3) -#' res <- .BEI_EMWeighting(var_exp, aweights) -#' dim(res) -#' # time -#' # 2 -#' @noRd +#'Atomic BEI_EMWeighting +#'@param var_exp Variable (e.g. precipitation, temperature, NAO index) +#' array from a SFS with a temporal dimension, +#' by default 'time', and dimension 'member'. +#'@param aweights Normalized weights array with a temporal dimension, +#' by default 'time', and dimension 'member' +#'@param time_dim_name A character string indicating the name of the +#' temporal dimension, by default 'time'. +#'@return .BEI_EMWeighting returns an array of with a temporal dimension, +#'by default 'time', containing the weighted ensemble means. +#'@examples +#'# Example for the Atomic BEI_EMWeighting function +#'var_exp <- 1 : 6 +#'dim(var_exp) <- c(time = 2, member = 3) +#'aweights <- c(0.28, 0.15, 0.69, 0.64, 0.42, 0.17) +#'dim(aweights) <- c(time = 2, member = 3) +#'res <- .BEI_EMWeighting(var_exp, aweights) +#'dim(res) +#'# time +#'# 2 +#'@noRd .BEI_EMWeighting <- function(var_exp, aweights, time_dim_name = 'time') { posTime <- match(time_dim_name, names(dim(var_exp))) @@ -280,61 +279,61 @@ BEI_EMWeighting <- function(var_exp, aweights, time_dim_name = 'time') { #' Computing the weighted tercile probabilities for SFSs. -#' @author Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} +#'@author Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} #' -#' @description This function implements the computation to obtain the tercile -#' probabilities for a weighted variable for SFSs using a normalized weights array, +#'@description This function implements the computation to obtain the tercile +#'probabilities for a weighted variable for SFSs using a normalized weights array, #' -#' @references Regionally improved seasonal forecast of precipitation through Best -#' estimation of winter NAO, Sanchez-Garcia, E. et al., -#' Adv. Sci. Res., 16, 165174, 2019, https://doi.org/10.5194/asr-16-165-2019 +#'@references Regionally improved seasonal forecast of precipitation through Best +#'estimation of winter NAO, Sanchez-Garcia, E. et al., +#'Adv. Sci. Res., 16, 165174, 2019, \url{https://doi.org/10.5194/asr-16-165-2019} #' -#' @param var_exp Variable (e.g. precipitation, temperature, NAO index) -#' array from a SFS with at least dimensions (time, member) for a spatially -#' aggregated variable or dimensions (time, member, lat, lon) for a spatial -#' variable, as 'time' the spatial dimension by default. -#' @param aweights Normalized weights array with at least dimensions -#' (time, member), when 'time' is the temporal dimension as default. -#' @param terciles A numeric array with at least one dimension 'tercil' equal to -#' 2, the first element is the lower tercil for a hindcast period, and the second -#' element is the upper tercile. -#' @param time_dim_name A character string indicating the name of the -#' temporal dimension, by default 'time'. +#'@param var_exp Variable (e.g. precipitation, temperature, NAO index) +#' array from a SFS with at least dimensions (time, member) for a spatially +#' aggregated variable or dimensions (time, member, lat, lon) for a spatial +#' variable, as 'time' the spatial dimension by default. +#'@param aweights Normalized weights array with at least dimensions +#' (time, member), when 'time' is the temporal dimension as default. +#'@param terciles A numeric array with at least one dimension 'tercil' equal to +#' 2, the first element is the lower tercil for a hindcast period, and the second +#' element is the upper tercile. +#'@param time_dim_name A character string indicating the name of the +#' temporal dimension, by default 'time'. #' -#' @return BEI_ProbsWeighting() returns an array with at least two or four -#' dimensions depending if the variable is a spatially aggregated variable -#' (as e.g. NAO index)(time, tercil) or it is spatial variable (as e.g. -#' precipitation or temperature)(time, tercile, lat, lon), containing the -#' terciles probabilities computing with weighted members. -#' The first tercil is the lower tercile, the second is the normal tercile and -#' the third is the upper tercile. +#'@return BEI_ProbsWeighting() returns an array with at least two or four +#'dimensions depending if the variable is a spatially aggregated variable +#'(as e.g. NAO index)(time, tercil) or it is spatial variable (as e.g. +#'precipitation or temperature)(time, tercile, lat, lon), containing the +#'terciles probabilities computing with weighted members. +#'The first tercil is the lower tercile, the second is the normal tercile and +#'the third is the upper tercile. #' -#' @import multiApply +#'@import multiApply #' -#' @examples -#' # Example 1 -#' var_exp <- 1 : (2 * 4) -#' dim(var_exp) <- c(time = 2, member = 4) -#' aweights<- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3) -#' dim(aweights) <- c(time = 2, member = 4) -#' terciles <- c(2.5,5) -#' dim(terciles) <- c(tercil = 2) -#' res <- BEI_ProbsWeighting(var_exp, aweights, terciles) -#' dim(res) -#' # time tercil -#' # 2 3 -#' # Example 2 -#' var_exp <- rnorm(48, 50, 9) -#' dim(var_exp) <- c(time = 2, member = 4, lat = 2, lon = 3) -#' aweights<- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3) -#' dim(aweights) <- c(time = 2, member = 4) -#' terciles <- rep(c(48,50), 2*3) -#' dim(terciles) <- c(tercil = 2, lat = 2, lon = 3) -#' res <- BEI_ProbsWeighting(var_exp, aweights, terciles) -#' dim(res) -#' # time tercil lat lon -#' # 2 3 2 3 -#' @noRd +#'@examples +#'# Example 1 +#'var_exp <- 1 : (2 * 4) +#'dim(var_exp) <- c(time = 2, member = 4) +#'aweights<- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3) +#'dim(aweights) <- c(time = 2, member = 4) +#'terciles <- c(2.5,5) +#'dim(terciles) <- c(tercil = 2) +#'res <- BEI_ProbsWeighting(var_exp, aweights, terciles) +#'dim(res) +#'# time tercil +#'# 2 3 +#'# Example 2 +#'var_exp <- rnorm(48, 50, 9) +#'dim(var_exp) <- c(time = 2, member = 4, lat = 2, lon = 3) +#'aweights<- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3) +#'dim(aweights) <- c(time = 2, member = 4) +#'terciles <- rep(c(48,50), 2*3) +#'dim(terciles) <- c(tercil = 2, lat = 2, lon = 3) +#'res <- BEI_ProbsWeighting(var_exp, aweights, terciles) +#'dim(res) +#'# time tercil lat lon +#'# 2 3 2 3 +#'@noRd BEI_ProbsWeighting <- function(var_exp, aweights, terciles, time_dim_name = 'time') { @@ -409,36 +408,36 @@ BEI_ProbsWeighting <- function(var_exp, aweights, terciles, return(res) } -#' Atomic BEI_ProbsWeighting -#' @param var_exp Variable (e.g. precipitation, temperature, NAO index) -#' array from a SFS with a temporal dimension, -#' by default 'time', and dimension 'member'. -#' @param aweights Normalized weights array with a temporal dimension, -#' by default 'time', and dimension 'member' -#' @param terciles A numeric array with one dimension 'tercil' equal to 2, -#' the first element is the lower tercil for a hindcast period, and the second -#' element is the upper tercile. -#' @param time_dim_name A character string indicating the name of the -#' temporal dimension, by default 'time'. +#'Atomic BEI_ProbsWeighting +#'@param var_exp Variable (e.g. precipitation, temperature, NAO index) +#' array from a SFS with a temporal dimension, +#' by default 'time', and dimension 'member'. +#'@param aweights Normalized weights array with a temporal dimension, +#' by default 'time', and dimension 'member' +#'@param terciles A numeric array with one dimension 'tercil' equal to 2, +#' the first element is the lower tercil for a hindcast period, and the second +#' element is the upper tercile. +#'@param time_dim_name A character string indicating the name of the +#' temporal dimension, by default 'time'. #' -#' @return .BEI_ProbsWeighting returns an array of with a temporal dimension, -#' as default 'time', and 'tercil' dimension, containing the probabilities -#' for each tercile computing with weighted members. -#' The firt tercil is the lower tercile, the second is the normal tercile and -#' the third is the upper tercile. -#' @examples -#' # Example -#' var_exp <- 1 : 8 -#' dim(var_exp) <- c(stime = 2, member = 4) -#' aweights <- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3) -#' dim(aweights) <- c(stime = 2, member = 4) -#' terciles <- quantile(1:8, probs = c(1/3, 2/3)) -#' dim(terciles) <- c(tercil = 2) -#' res <- .BEI_ProbsWeighting(var_exp, aweights, terciles, time_dim_name = 'stime') -#' dim(res) -#' # stime tercil -#' # 2 3 -#' @noRd +#'@return .BEI_ProbsWeighting returns an array of with a temporal dimension, +#'as default 'time', and 'tercil' dimension, containing the probabilities +#'for each tercile computing with weighted members. +#'The firt tercil is the lower tercile, the second is the normal tercile and +#'the third is the upper tercile. +#'@examples +#'# Example +#'var_exp <- 1 : 8 +#'dim(var_exp) <- c(stime = 2, member = 4) +#'aweights <- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3) +#'dim(aweights) <- c(stime = 2, member = 4) +#'terciles <- quantile(1:8, probs = c(1/3, 2/3)) +#'dim(terciles) <- c(tercil = 2) +#'res <- .BEI_ProbsWeighting(var_exp, aweights, terciles, time_dim_name = 'stime') +#'dim(res) +#'# stime tercil +#'# 2 3 +#'@noRd .BEI_ProbsWeighting <- function(var_exp, aweights, terciles, time_dim_name = 'time') { if(any(is.na(var_exp)) || any(is.na(aweights))){ @@ -469,54 +468,54 @@ BEI_ProbsWeighting <- function(var_exp, aweights, terciles, return(probTercile) } -#' Computing the weighted terciles for SFSs. -#' @author Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} +#'Computing the weighted terciles for SFSs. +#'@author Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} #' -#' @description This function implements the computation to obtain the terciles -#' for a weighted variable for SFSs using a normalized weights array, +#'@description This function implements the computation to obtain the terciles +#'for a weighted variable for SFSs using a normalized weights array, #' -#' @references Regionally improved seasonal forecast of precipitation through Best -#' estimation of winter NAO, Sanchez-Garcia, E. et al., -#' Adv. Sci. Res., 16, 165174, 2019, https://doi.org/10.5194/asr-16-165-2019 +#'@references Regionally improved seasonal forecast of precipitation through Best +#'estimation of winter NAO, Sanchez-Garcia, E. et al., +#'Adv. Sci. Res., 16, 165174, 2019, https://doi.org/10.5194/asr-16-165-2019 #' -#' @param var_exp Variable (e.g. precipitation, temperature, NAO index) -#' array from a SFS with at least dimensions (time, member) for a spatially -#' aggregated variable or dimensions (time, member, lat, lon) for a spatial -#' variable, as 'time' the spatial dimension by default. -#' @param aweights Normalized weights array with at least dimensions -#' (time, member), when 'time' is the temporal dimension as default. -#' @param time_dim_name A character string indicating the name of the -#' temporal dimension, by default 'time'. +#'@param var_exp Variable (e.g. precipitation, temperature, NAO index) +#' array from a SFS with at least dimensions (time, member) for a spatially +#' aggregated variable or dimensions (time, member, lat, lon) for a spatial +#' variable, as 'time' the spatial dimension by default. +#'@param aweights Normalized weights array with at least dimensions +#' (time, member), when 'time' is the temporal dimension as default. +#'@param time_dim_name A character string indicating the name of the +#' temporal dimension, by default 'time'. #' -#' @return BEI_TercilesWeighting() returns an array with at least one -#' dimension depending if the variable is a spatially aggregated variable -#' (as e.g. NAO index)(tercil) or it is spatial variable (as e.g. -#' precipitation or temperature)(tercil, lat, lon), containing the -#' terciles computing with weighted members. -#' The first tercil is the lower tercile, the second is the upper tercile. +#'@return BEI_TercilesWeighting() returns an array with at least one +#'dimension depending if the variable is a spatially aggregated variable +#'(as e.g. NAO index)(tercil) or it is spatial variable (as e.g. +#'precipitation or temperature)(tercil, lat, lon), containing the +#'terciles computing with weighted members. +#'The first tercil is the lower tercile, the second is the upper tercile. #' -#' @import multiApply +#'@import multiApply #' -#' @examples -#' # Example 1 -#' var_exp <- 1 : (2 * 4) -#' dim(var_exp) <- c(time = 2, member = 4) -#' aweights<- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3) -#' dim(aweights) <- c(time = 2, member = 4) -#' res <- BEI_TercilesWeighting(var_exp, aweights) -#' dim(res) -#' # tercil -#' # 2 -#' # Example 2 -#' var_exp <- rnorm(48, 50, 9) -#' dim(var_exp) <- c(time = 2, member = 4, lat = 2, lon = 3) -#' aweights<- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3) -#' dim(aweights) <- c(time = 2, member = 4) -#' res <- BEI_TercilesWeighting(var_exp, aweights) -#' dim(res) -#' # tercil lat lon -#' # 2 2 3 -#' @noRd +#'@examples +#'# Example 1 +#'var_exp <- 1 : (2 * 4) +#'dim(var_exp) <- c(time = 2, member = 4) +#'aweights<- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3) +#'dim(aweights) <- c(time = 2, member = 4) +#'res <- BEI_TercilesWeighting(var_exp, aweights) +#'dim(res) +#'# tercil +#'# 2 +#'# Example 2 +#'var_exp <- rnorm(48, 50, 9) +#'dim(var_exp) <- c(time = 2, member = 4, lat = 2, lon = 3) +#'aweights<- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3) +#'dim(aweights) <- c(time = 2, member = 4) +#'res <- BEI_TercilesWeighting(var_exp, aweights) +#'dim(res) +#'# tercil lat lon +#'# 2 2 3 +#'@noRd BEI_TercilesWeighting <- function(var_exp, aweights, time_dim_name = 'time') { if (!is.character(time_dim_name)) { @@ -565,30 +564,30 @@ BEI_TercilesWeighting <- function(var_exp, aweights, time_dim_name = 'time') { return(res) } -#' Atomic BEI_TercilesWeighting -#' @param var_exp Variable (e.g. precipitation, temperature, NAO index) -#' array from a SFS with a temporal dimension, -#' by default 'time', and dimension 'member'. -#' @param aweights Normalized weights array with a temporal dimension, -#' by default 'time', and dimension 'member' -#' @param time_dim_name A character string indicating the name of the -#' temporal dimension, by default 'time'. -#' @return .BEI_TercilesWeighting returns a numeric array with dimension tercil -#' equal to 2, the first is the lower tercil and the second the upper tercile, -#' computing with weighted members considering all members and all period. -#' If any member value for any period is NA , the terciles are not computed, and -#' the function return NA value as tercile upper and lower. -#' @examples -#' # Example -#' var_exp <- 1 : 8 -#' dim(var_exp) <- c(stime = 2, member = 4) -#' aweights <- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3) -#' dim(aweights) <- c(stime = 2, member = 4) -#' res <- .BEI_TercilesWeighting(var_exp, aweights, time_dim_name = 'stime') -#' dim(res) -#' # tercil -#' # 2 -#' @noRd +#'Atomic BEI_TercilesWeighting +#'@param var_exp Variable (e.g. precipitation, temperature, NAO index) +#' array from a SFS with a temporal dimension, +#' by default 'time', and dimension 'member'. +#'@param aweights Normalized weights array with a temporal dimension, +#' by default 'time', and dimension 'member' +#'@param time_dim_name A character string indicating the name of the +#' temporal dimension, by default 'time'. +#'@return .BEI_TercilesWeighting returns a numeric array with dimension tercil +#'equal to 2, the first is the lower tercil and the second the upper tercile, +#'computing with weighted members considering all members and all period. +#'If any member value for any period is NA , the terciles are not computed, and +#'the function return NA value as tercile upper and lower. +#'@examples +#'# Example +#'var_exp <- 1 : 8 +#'dim(var_exp) <- c(stime = 2, member = 4) +#'aweights <- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3) +#'dim(aweights) <- c(stime = 2, member = 4) +#'res <- .BEI_TercilesWeighting(var_exp, aweights, time_dim_name = 'stime') +#'dim(res) +#'# tercil +#'# 2 +#'@noRd .BEI_TercilesWeighting <- function(var_exp, aweights, time_dim_name = 'time') { if(any(is.na(var_exp)) || any(is.na(aweights))){ terciles_exp <- array(c(NA, NA), dim = c(tercil = 2)) diff --git a/R/CST_Calibration.R b/R/CST_Calibration.R index f03d5d0557268e4f9438e7704c34a979502db125..cccd7394a0c488958454ab7f65f313399bc2db5e 100644 --- a/R/CST_Calibration.R +++ b/R/CST_Calibration.R @@ -2,22 +2,59 @@ #' #'@author Verónica Torralba, \email{veronica.torralba@bsc.es} #'@author Bert Van Schaeybroeck, \email{bertvs@meteo.be} -#'@description Equivalent to function \code{Calibration} but for objects of class \code{s2dv_cube}. +#'@description Equivalent to function \code{Calibration} but for objects of +#'class \code{s2dv_cube}. #' -#'@param exp an object of class \code{s2dv_cube} as returned by \code{CST_Load} function, containing the seasonal hindcast experiment data in the element named \code{$data}. The hindcast is used to calibrate the forecast in case the forecast is provided; if not, the same hindcast will be calibrated instead. -#'@param obs an object of class \code{s2dv_cube} as returned by \code{CST_Load} function, containing the observed data in the element named \code{$data}. -#'@param exp_cor an optional object of class \code{s2dv_cube} as returned by \code{CST_Load} function, containing the seasonal forecast experiment data in the element named \code{$data}. If the forecast is provided, it will be calibrated using the hindcast and observations; if not, the hindcast will be calibrated instead. -#'@param cal.method is the calibration method used, can be either \code{bias}, \code{evmos}, \code{mse_min}, \code{crps_min} or \code{rpc-based}. Default value is \code{mse_min}. -#'@param eval.method is the sampling method used, can be either \code{in-sample} or \code{leave-one-out}. Default value is the \code{leave-one-out} cross validation. In case the forecast is provided, any chosen eval.method is over-ruled and a third option is used. -#'@param multi.model is a boolean that is used only for the \code{mse_min} method. If multi-model ensembles or ensembles of different sizes are used, it must be set to \code{TRUE}. By default it is \code{FALSE}. Differences between the two approaches are generally small but may become large when using small ensemble sizes. Using multi.model when the calibration method is \code{bias}, \code{evmos} or \code{crps_min} will not affect the result. -#'@param na.fill is a boolean that indicates what happens in case calibration is not possible or will yield unreliable results. This happens when three or less forecasts-observation pairs are available to perform the training phase of the calibration. By default \code{na.fill} is set to true such that NA values will be returned. If \code{na.fill} is set to false, the uncorrected data will be returned. -#'@param na.rm is a boolean that indicates whether to remove the NA values or not. The default value is \code{TRUE}. See Details section for further information about its use and compatibility with \code{na.fill}. -#'@param apply_to is a character string that indicates whether to apply the calibration to all the forecast (\code{"all"}) or only to those where the correlation between the ensemble mean and the observations is statistically significant (\code{"sign"}). Only useful if \code{cal.method == "rpc-based"}. -#'@param alpha is a numeric value indicating the significance level for the correlation test. Only useful if \code{cal.method == "rpc-based" & apply_to == "sign"}. -#'@param memb_dim is a character string indicating the name of the member dimension. By default, it is set to 'member'. -#'@param sdate_dim is a character string indicating the name of the start date dimension. By default, it is set to 'sdate'. -#'@param ncores is an integer that indicates the number of cores for parallel computations using multiApply function. The default value is one. -#'@return an object of class \code{s2dv_cube} containing the calibrated forecasts in the element \code{$data} with the same dimensions as the one in the exp object. +#'@param exp An object of class \code{s2dv_cube} as returned by \code{CST_Load} +#' function, containing the seasonal hindcast experiment data in the element +#' named \code{$data}. The hindcast is used to calibrate the forecast in case +#' the forecast is provided; if not, the same hindcast will be calibrated +#' instead. +#'@param obs An object of class \code{s2dv_cube} as returned by \code{CST_Load} +#' function, containing the observed data in the element named \code{$data}. +#'@param exp_cor An optional object of class \code{s2dv_cube} as returned by +#' \code{CST_Load} function, containing the seasonal forecast experiment data +#' in the element named \code{$data}. If the forecast is provided, it will be +#' calibrated using the hindcast and observations; if not, the hindcast will be +#' calibrated instead. +#'@param cal.method Is the calibration method used, can be either \code{bias}, +#' \code{evmos}, \code{mse_min}, \code{crps_min} or \code{rpc-based}. Default +#' value is \code{mse_min}. +#'@param eval.method Is the sampling method used, can be either \code{in-sample} +#' or \code{leave-one-out}. Default value is the \code{leave-one-out} cross +#' validation. In case the forecast is provided, any chosen eval.method is +#' over-ruled and a third option is used. +#'@param multi.model Is a boolean that is used only for the \code{mse_min} +#' method. If multi-model ensembles or ensembles of different sizes are used, +#' it must be set to \code{TRUE}. By default it is \code{FALSE}. Differences +#' between the two approaches are generally small but may become large when +#' using small ensemble sizes. Using multi.model when the calibration method is +#' \code{bias}, \code{evmos} or \code{crps_min} will not affect the result. +#'@param na.fill Is a boolean that indicates what happens in case calibration is +#' not possible or will yield unreliable results. This happens when three or +#' less forecasts-observation pairs are available to perform the training phase +#' of the calibration. By default \code{na.fill} is set to true such that NA +#' values will be returned. If \code{na.fill} is set to false, the uncorrected +#' data will be returned. +#'@param na.rm Is a boolean that indicates whether to remove the NA values or +#' not. The default value is \code{TRUE}. See Details section for further +#' information about its use and compatibility with \code{na.fill}. +#'@param apply_to Is a character string that indicates whether to apply the +#' calibration to all the forecast (\code{"all"}) or only to those where the +#' correlation between the ensemble mean and the observations is statistically +#' significant (\code{"sign"}). Only useful if \code{cal.method == "rpc-based"}. +#'@param alpha Is a numeric value indicating the significance level for the +#' correlation test. Only useful if \code{cal.method == "rpc-based" & +#' apply_to == "sign"}. +#'@param memb_dim Is a character string indicating the name of the member +#' dimension. By default, it is set to 'member'. +#'@param sdate_dim Is a character string indicating the name of the start date +#' dimension. By default, it is set to 'sdate'. +#'@param ncores Is an integer that indicates the number of cores for parallel +#' computations using multiApply function. The default value is one. +#'@return An object of class \code{s2dv_cube} containing the calibrated +#'forecasts in the element \code{$data} with the same dimensions as the one in +#'the exp object. #' #'@importFrom s2dv InsertDim #'@import abind @@ -36,7 +73,8 @@ #'obs <- list(data = obs1, lat = lat, lon = lon) #'attr(exp, 'class') <- 's2dv_cube' #'attr(obs, 'class') <- 's2dv_cube' -#'a <- CST_Calibration(exp = exp, obs = obs, cal.method = "mse_min", eval.method = "in-sample") +#'a <- CST_Calibration(exp = exp, obs = obs, cal.method = "mse_min", +#' eval.method = "in-sample") #'str(a) #' #'# Example 2: @@ -54,10 +92,10 @@ #'attr(exp, 'class') <- 's2dv_cube' #'attr(obs, 'class') <- 's2dv_cube' #'attr(exp_cor, 'class') <- 's2dv_cube' -#'a <- CST_Calibration(exp = exp, obs = obs, exp_cor = exp_cor, cal.method = "evmos") +#'a <- CST_Calibration(exp = exp, obs = obs, exp_cor = exp_cor, +#' cal.method = "evmos") #'str(a) #'@export - CST_Calibration <- function(exp, obs, exp_cor = NULL, cal.method = "mse_min", eval.method = "leave-one-out", multi.model = FALSE, na.fill = TRUE, na.rm = TRUE, apply_to = NULL, alpha = NULL, @@ -113,27 +151,83 @@ CST_Calibration <- function(exp, obs, exp_cor = NULL, cal.method = "mse_min", #' #'@author Verónica Torralba, \email{veronica.torralba@bsc.es} #'@author Bert Van Schaeybroeck, \email{bertvs@meteo.be} -#'@description Five types of member-by-member bias correction can be performed. The \code{"bias"} method corrects the bias only, the \code{"evmos"} method applies a variance inflation technique to ensure the correction of the bias and the correspondence of variance between forecast and observation (Van Schaeybroeck and Vannitsem, 2011). The ensemble calibration methods \code{"mse_min"} and \code{"crps_min"} correct the bias, the overall forecast variance and the ensemble spread as described in Doblas-Reyes et al. (2005) and Van Schaeybroeck and Vannitsem (2015), respectively. While the \code{"mse_min"} method minimizes a constrained mean-squared error using three parameters, the \code{"crps_min"} method features four parameters and minimizes the Continuous Ranked Probability Score (CRPS). The \code{"rpc-based"} method adjusts the forecast variance ensuring that the ratio of predictable components (RPC) is equal to one, as in Eade et al. (2014). -#'@description Both in-sample or our out-of-sample (leave-one-out cross validation) calibration are possible. -#'@references Doblas-Reyes F.J, Hagedorn R, Palmer T.N. The rationale behind the success of multi-model ensembles in seasonal forecasting-II calibration and combination. Tellus A. 2005;57:234-252. doi:10.1111/j.1600-0870.2005.00104.x -#'@references Eade, R., Smith, D., Scaife, A., Wallace, E., Dunstone, N., Hermanson, L., & Robinson, N. (2014). Do seasonal-to-decadal climate predictions underestimate the predictability of the read world? Geophysical Research Letters, 41(15), 5620-5628. doi: 10.1002/2014GL061146 -#'@references Van Schaeybroeck, B., & Vannitsem, S. (2011). Post-processing through linear regression. Nonlinear Processes in Geophysics, 18(2), 147. doi:10.5194/npg-18-147-2011 -#'@references Van Schaeybroeck, B., & Vannitsem, S. (2015). Ensemble post-processing using member-by-member approaches: theoretical aspects. Quarterly Journal of the Royal Meteorological Society, 141(688), 807-818. doi:10.1002/qj.2397 +#'@description Five types of member-by-member bias correction can be performed. +#'The \code{"bias"} method corrects the bias only, the \code{"evmos"} method +#'applies a variance inflation technique to ensure the correction of the bias +#'and the correspondence of variance between forecast and observation (Van +#'Schaeybroeck and Vannitsem, 2011). The ensemble calibration methods +#'\code{"mse_min"} and \code{"crps_min"} correct the bias, the overall forecast +#'variance and the ensemble spread as described in Doblas-Reyes et al. (2005) +#'and Van Schaeybroeck and Vannitsem (2015), respectively. While the +#'\code{"mse_min"} method minimizes a constrained mean-squared error using three +#'parameters, the \code{"crps_min"} method features four parameters and +#'minimizes the Continuous Ranked Probability Score (CRPS). The +#'\code{"rpc-based"} method adjusts the forecast variance ensuring that the +#'ratio of predictable components (RPC) is equal to one, as in Eade et al. (2014). +#'@description Both in-sample or our out-of-sample (leave-one-out cross +#'validation) calibration are possible. +#'@references Doblas-Reyes F.J, Hagedorn R, Palmer T.N. The rationale behind the +#'success of multi-model ensembles in seasonal forecasting-II calibration and +#'combination. Tellus A. 2005;57:234-252. +#'doi:10.1111/j.1600-0870.2005.00104.x +#'@references Eade, R., Smith, D., Scaife, A., Wallace, E., Dunstone, N., +#'Hermanson, L., & Robinson, N. (2014). Do seasonal-to-decadal climate +#'predictions underestimate the predictability of the read world? Geophysical +#'Research Letters, 41(15), 5620-5628. doi: 10.1002/2014GL061146 +#'@references Van Schaeybroeck, B., & Vannitsem, S. (2011). Post-processing +#'through linear regression. Nonlinear Processes in Geophysics, 18(2), 147. +#'doi:10.5194/npg-18-147-2011 +#'@references Van Schaeybroeck, B., & Vannitsem, S. (2015). Ensemble +#'post-processing using member-by-member approaches: theoretical aspects. +#'Quarterly Journal of the Royal Meteorological Society, 141(688), 807-818. +#'doi:10.1002/qj.2397 #' -#'@param exp a multidimensional array with named dimensions (at least 'sdate' and 'member') containing the seasonal hindcast experiment data. The hindcast is used to calibrate the forecast in case the forecast is provided; if not, the same hindcast will be calibrated instead. -#'@param obs a multidimensional array with named dimensions (at least 'sdate') containing the observed data. -#'@param exp_cor an optional multidimensional array with named dimensions (at least 'sdate' and 'member') containing the seasonal forecast experiment data. If the forecast is provided, it will be calibrated using the hindcast and observations; if not, the hindcast will be calibrated instead. -#'@param cal.method is the calibration method used, can be either \code{bias}, \code{evmos}, \code{mse_min}, \code{crps_min} or \code{rpc-based}. Default value is \code{mse_min}. -#'@param eval.method is the sampling method used, can be either \code{in-sample} or \code{leave-one-out}. Default value is the \code{leave-one-out} cross validation. In case the forecast is provided, any chosen eval.method is over-ruled and a third option is used. -#'@param multi.model is a boolean that is used only for the \code{mse_min} method. If multi-model ensembles or ensembles of different sizes are used, it must be set to \code{TRUE}. By default it is \code{FALSE}. Differences between the two approaches are generally small but may become large when using small ensemble sizes. Using multi.model when the calibration method is \code{bias}, \code{evmos} or \code{crps_min} will not affect the result. -#'@param na.fill is a boolean that indicates what happens in case calibration is not possible or will yield unreliable results. This happens when three or less forecasts-observation pairs are available to perform the training phase of the calibration. By default \code{na.fill} is set to true such that NA values will be returned. If \code{na.fill} is set to false, the uncorrected data will be returned. -#'@param na.rm is a boolean that indicates whether to remove the NA values or not. The default value is \code{TRUE}. -#'@param apply_to is a character string that indicates whether to apply the calibration to all the forecast (\code{"all"}) or only to those where the correlation between the ensemble mean and the observations is statistically significant (\code{"sign"}). Only useful if \code{cal.method == "rpc-based"}. -#'@param alpha is a numeric value indicating the significance level for the correlation test. Only useful if \code{cal.method == "rpc-based" & apply_to == "sign"}. -#'@param memb_dim is a character string indicating the name of the member dimension. By default, it is set to 'member'. -#'@param sdate_dim is a character string indicating the name of the start date dimension. By default, it is set to 'sdate'. -#'@param ncores is an integer that indicates the number of cores for parallel computations using multiApply function. The default value is one. -#'@return an array containing the calibrated forecasts with the same dimensions as the \code{exp} array. +#'@param exp A multidimensional array with named dimensions (at least 'sdate' +#' and 'member') containing the seasonal hindcast experiment data. The hindcast +#' is used to calibrate the forecast in case the forecast is provided; if not, +#' the same hindcast will be calibrated instead. +#'@param obs A multidimensional array with named dimensions (at least 'sdate') +#' containing the observed data. +#'@param exp_cor An optional multidimensional array with named dimensions (at +#' least 'sdate' and 'member') containing the seasonal forecast experiment data. +#' If the forecast is provided, it will be calibrated using the hindcast and +#' observations; if not, the hindcast will be calibrated instead. +#'@param cal.method Is the calibration method used, can be either \code{bias}, +#' \code{evmos}, \code{mse_min}, \code{crps_min} or \code{rpc-based}. Default +#' value is \code{mse_min}. +#'@param eval.method Is the sampling method used, can be either \code{in-sample} +#' or \code{leave-one-out}. Default value is the \code{leave-one-out} cross +#' validation. In case the forecast is provided, any chosen eval.method is +#' over-ruled and a third option is used. +#'@param multi.model Is a boolean that is used only for the \code{mse_min} +#' method. If multi-model ensembles or ensembles of different sizes are used, +#' it must be set to \code{TRUE}. By default it is \code{FALSE}. Differences +#' between the two approaches are generally small but may become large when +#' using small ensemble sizes. Using multi.model when the calibration method is +#' \code{bias}, \code{evmos} or \code{crps_min} will not affect the result. +#'@param na.fill Is a boolean that indicates what happens in case calibration is +#' not possible or will yield unreliable results. This happens when three or +#' less forecasts-observation pairs are available to perform the training phase +#' of the calibration. By default \code{na.fill} is set to true such that NA +#' values will be returned. If \code{na.fill} is set to false, the uncorrected +#' data will be returned. +#'@param na.rm Is a boolean that indicates whether to remove the NA values or +#' not. The default value is \code{TRUE}. +#'@param apply_to Is a character string that indicates whether to apply the +#' calibration to all the forecast (\code{"all"}) or only to those where the +#' correlation between the ensemble mean and the observations is statistically +#' significant (\code{"sign"}). Only useful if \code{cal.method == "rpc-based"}. +#'@param alpha Is a numeric value indicating the significance level for the +#' correlation test. Only useful if \code{cal.method == "rpc-based" & +#' apply_to == "sign"}. +#'@param memb_dim Is a character string indicating the name of the member +#' dimension. By default, it is set to 'member'. +#'@param sdate_dim Is a character string indicating the name of the start date +#' dimension. By default, it is set to 'sdate'. +#'@param ncores Is an integer that indicates the number of cores for parallel +#' computations using multiApply function. The default value is one. +#'@return An array containing the calibrated forecasts with the same dimensions +#'as the \code{exp} array. #' #'@importFrom s2dv InsertDim MeanDims Reorder #'@import abind @@ -143,7 +237,15 @@ CST_Calibration <- function(exp, obs, exp_cor = NULL, cal.method = "mse_min", #'@seealso \code{\link{CST_Load}} #' #'@details -#'Both the \code{na.fill} and \code{na.rm} parameters can be used to indicate how the function has to handle the NA values. The \code{na.fill} parameter checks whether there are more than three forecast-observations pairs to perform the computation. In case there are three or less pairs, the computation is not carried out, and the value returned by the function depends on the value of this parameter (either NA if \code{na.fill == TRUE} or the uncorrected value if \code{na.fill == TRUE}). On the other hand, \code{na.rm} is used to indicate the function whether to remove the missing values during the computation of the parameters needed to perform the calibration. +#'Both the \code{na.fill} and \code{na.rm} parameters can be used to indicate +#'how the function has to handle the NA values. The \code{na.fill} parameter +#'checks whether there are more than three forecast-observations pairs to +#'perform the computation. In case there are three or less pairs, the +#'computation is not carried out, and the value returned by the function depends +#'on the value of this parameter (either NA if \code{na.fill == TRUE} or the +#'uncorrected value if \code{na.fill == TRUE}). On the other hand, \code{na.rm} +#'is used to indicate the function whether to remove the missing values during +#'the computation of the parameters needed to perform the calibration. #' #'@examples #'mod1 <- 1 : (1 * 3 * 4 * 5 * 6 * 7) diff --git a/R/CST_CategoricalEnsCombination.R b/R/CST_CategoricalEnsCombination.R index 3dc23579ccafaca5349ee7d7ea3a646fc371912e..55495c5ee713cd2848be66fef1e8a93ddd9c0dfa 100644 --- a/R/CST_CategoricalEnsCombination.R +++ b/R/CST_CategoricalEnsCombination.R @@ -1,81 +1,99 @@ -#' Make categorical forecast based on a multi-model forecast with potential for calibrate +#'Make categorical forecast based on a multi-model forecast with potential for +#'calibrate #' #'@author Bert Van Schaeybroeck, \email{bertvs@meteo.be} -#'@description This function converts a multi-model ensemble forecast -#' into a categorical forecast by giving the probability -#' for each category. Different methods are available to combine -#' the different ensemble forecasting models into -#' probabilistic categorical forecasts. +#'@description This function converts a multi-model ensemble forecast into a +#'categorical forecast by giving the probability for each category. Different +#'methods are available to combine the different ensemble forecasting models +#'into probabilistic categorical forecasts. #' -#' Motivation: -#' Beyond the short range, the unpredictable component of weather -#' predictions becomes substantial due to the chaotic nature of the earth -#' system. Therefore, predictions can mostly be skillful when used in a probabilistic sense. -#' In practice this is done using ensemble forecasts. It is then common to -#' convert the ensemble forecasts to occurence probabilities for different categories. -#' These categories typically are taken as terciles from climatolgical distributions. -#' For instance for temperature, there is a cold, normal and warm class. -#' Commonly multiple ensemble forecasting systems -#' are available but some models may be more competitive than others -#' for the variable, region and user need under consideration. Therefore, -#' when calculating the category probabilities, the ensemble members of -#' the different forecasting system may be differently weighted. -#' Such weighting is typically done by comparison of the ensemble forecasts -#' with observations. +#'Motivation: Beyond the short range, the unpredictable component of weather +#'predictions becomes substantial due to the chaotic nature of the earth system. +#'Therefore, predictions can mostly be skillful when used in a probabilistic +#'sense. In practice this is done using ensemble forecasts. It is then common to +#'convert the ensemble forecasts to occurence probabilities for different +#'categories. These categories typically are taken as terciles from +#'climatolgical distributions. For instance for temperature, there is a cold, +#'normal and warm class. Commonly multiple ensemble forecasting systems are +#'available but some models may be more competitive than others for the +#'variable, region and user need under consideration. Therefore, when +#'calculating the category probabilities, the ensemble members of the different +#'forecasting system may be differently weighted. Such weighting is typically +#'done by comparison of the ensemble forecasts with observations. #' -#' Description of the tool: -#' The tool considers all forecasts (all members from all forecasting systems) -#' and converts them into occurrence probabilities of different categories. -#' The amount of categories can be changed and are taken as the -#' climatological quantiles (e.g. terciles), extracted -#' from the observational data. -#' The methods that are available to combine the ensemble forecasting models into -#' probabilistic categorical forecasts are: 1) ensemble pooling where -#' all ensemble members of all ensemble systems are weighted equally, +#'Description of the tool: The tool considers all forecasts (all members from +#'all forecasting systems) and converts them into occurrence probabilities of +#'different categories. The amount of categories can be changed and are taken as +#'the climatological quantiles (e.g. terciles), extracted from the observational +#'data. The methods that are available to combine the ensemble forecasting +#'models into probabilistic categorical forecasts are: 1) ensemble pooling where +#'all ensemble members of all ensemble systems are weighted equally, #' 2) model combination where each model system is weighted equally, and, #' 3) model weighting. -#' The model weighting method is described in Rajagopalan et al. (2002), -#' Robertson et al. 2004 and Van Schaeybroeck and Vannitsem (2019). -#' More specifically, this method uses different weights for the -#' occurence probability predicted by the available models and by a climatological model -#' and optimizes the weights by minimizing the ignorance score. -#' Finally, the function can also be used to categorize the observations -#' in the categorical quantiles. -#' -#'@param exp an object of class \code{s2dv_cube} as returned by \code{CST_Load} function, containing the seasonal forecast experiment data in the element named \code{$data}. The amount of forecasting models is equal to the size of the \code{dataset} dimension of the data array. The amount of members per model may be different. The size of the \code{member} dimension of the data array is equal to the maximum of the ensemble members among the models. Models with smaller ensemble sizes have residual indices of \code{member} dimension in the data array filled with NA values. -#'@param obs an object of class \code{s2dv_cube} as returned by \code{CST_Load} function, containing the observed data in the element named \code{$data}. -#'@param amt.cat is the amount of categories. Equally-sized quantiles will be calculated based on the amount of categories. -#'@param cat.method method used to produce the categorical forecast, can be either \code{pool}, \code{comb}, \code{mmw} or \code{obs}. The method pool assumes equal weight for all ensemble members while the method comb assumes equal weight for each model. The weighting method is descirbed in Rajagopalan et al. (2002), Robertson et al. (2004) and Van Schaeybroeck and Vannitsem (2019). Finally, the \code{obs} method classifies the observations into the different categories and therefore contains only 0 and 1 values. -#'@param eval.method is the sampling method used, can be either \code{"in-sample"} or \code{"leave-one-out"}. Default value is the \code{"leave-one-out"} cross validation. +#'The model weighting method is described in Rajagopalan et al. (2002), +#'Robertson et al. 2004 and Van Schaeybroeck and Vannitsem (2019). More +#'specifically, this method uses different weights for the occurence probability +#'predicted by the available models and by a climatological model and optimizes +#'the weights by minimizing the ignorance score. Finally, the function can also +#'be used to categorize the observations in the categorical quantiles. +#' +#'@param exp An object of class \code{s2dv_cube} as returned by \code{CST_Load} +#' function, containing the seasonal forecast experiment data in the element +#' named \code{$data}. The amount of forecasting models is equal to the size of +#' the \code{dataset} dimension of the data array. The amount of members per +#' model may be different. The size of the \code{member} dimension of the data +#' array is equal to the maximum of the ensemble members among the models. +#' Models with smaller ensemble sizes have residual indices of \code{member} +#' dimension in the data array filled with NA values. +#'@param obs An object of class \code{s2dv_cube} as returned by \code{CST_Load} +#' function, containing the observed data in the element named \code{$data}. +#'@param amt.cat Is the amount of categories. Equally-sized quantiles will be +#' calculated based on the amount of categories. +#'@param cat.method Method used to produce the categorical forecast, can be +#' either \code{pool}, \code{comb}, \code{mmw} or \code{obs}. The method pool +#' assumes equal weight for all ensemble members while the method comb assumes +#' equal weight for each model. The weighting method is descirbed in +#' Rajagopalan et al. (2002), Robertson et al. (2004) and Van Schaeybroeck and +#' Vannitsem (2019). Finally, the \code{obs} method classifies the observations +#' into the different categories and therefore contains only 0 and 1 values. +#'@param eval.method Is the sampling method used, can be either +#' \code{"in-sample"} or \code{"leave-one-out"}. Default value is the +#' \code{"leave-one-out"} cross validation. #'@param ... other parameters to be passed on to the calibration procedure. #' -#'@return an object of class \code{s2dv_cube} containing the categorical forecasts in the element called \code{$data}. The first two dimensions of the returned object are named dataset and member and are both of size one. An additional dimension named category is introduced and is of size amt.cat. +#'@return An object of class \code{s2dv_cube} containing the categorical +#'forecasts in the element called \code{$data}. The first two dimensions of the +#'returned object are named dataset and member and are both of size one. An +#'additional dimension named category is introduced and is of size amt.cat. #' -#'@references Rajagopalan, B., Lall, U., & Zebiak, S. E. (2002). Categorical climate forecasts through regularization and optimal combination of multiple GCM ensembles. Monthly Weather Review, 130(7), 1792-1811. -#'@references Robertson, A. W., Lall, U., Zebiak, S. E., & Goddard, L. (2004). Improved combination of multiple atmospheric GCM ensembles for seasonal prediction. Monthly Weather Review, 132(12), 2732-2744. -#'@references Van Schaeybroeck, B., & Vannitsem, S. (2019). Postprocessing of Long-Range Forecasts. In Statistical Postprocessing of Ensemble Forecasts (pp. 267-290). +#'@references Rajagopalan, B., Lall, U., & Zebiak, S. E. (2002). Categorical +#'climate forecasts through regularization and optimal combination of multiple +#'GCM ensembles. Monthly Weather Review, 130(7), 1792-1811. +#'@references Robertson, A. W., Lall, U., Zebiak, S. E., & Goddard, L. (2004). +#'Improved combination of multiple atmospheric GCM ensembles for seasonal +#'prediction. Monthly Weather Review, 132(12), 2732-2744. +#'@references Van Schaeybroeck, B., & Vannitsem, S. (2019). Postprocessing of +#'Long-Range Forecasts. In Statistical Postprocessing of Ensemble Forecasts (pp. 267-290). #' #'@importFrom s2dv InsertDim #'@import abind #'@examples #' -#'mod1 <- 1 : (2 * 3 * 4 * 5 * 6 * 7) -#'dim(mod1) <- c(dataset = 2, member = 3, sdate = 4, ftime = 5, lat = 6, lon = 7) -#'mod1[ 2, 3, , , , ] <- NA +#'mod1 <- 1 : (2 * 2* 4 * 5 * 2 * 2) +#'dim(mod1) <- c(dataset = 2, member = 2, sdate = 4, ftime = 5, lat = 2, lon = 2) +#'mod1[2, 1, , , , ] <- NA #'dimnames(mod1)[[1]] <- c("MF", "UKMO") -#'obs1 <- 1 : (1 * 1 * 4 * 5 * 6 * 7) -#'dim(obs1) <- c(dataset = 1, member = 1, sdate = 4, ftime = 5, lat = 6, lon = 7) +#'obs1 <- 1 : (1 * 1 * 4 * 5 * 2 * 2) +#'dim(obs1) <- c(dataset = 1, member = 1, sdate = 4, ftime = 5, lat = 2, lon = 2) #'lon <- seq(0, 30, 5) #'lat <- seq(0, 25, 5) #'exp <- list(data = mod1, lat = lat, lon = lon) #'obs <- list(data = obs1, lat = lat, lon = lon) #'attr(exp, 'class') <- 's2dv_cube' #'attr(obs, 'class') <- 's2dv_cube' -#'\donttest{ #'a <- CST_CategoricalEnsCombination(exp = exp, obs = obs, amt.cat = 3, cat.method = "mmw") -#'} +#' #'@export - CST_CategoricalEnsCombination <- function(exp, obs, cat.method = "pool", eval.method = "leave-one-out", amt.cat = 3, ...) { if (!inherits(exp, "s2dv_cube") || !inherits(exp, "s2dv_cube")) { stop("Parameter 'exp' and 'obs' must be of the class 's2dv_cube', ", @@ -97,33 +115,57 @@ CST_CategoricalEnsCombination <- function(exp, obs, cat.method = "pool", eval.me return(exp) } -#' Make categorical forecast based on a multi-model forecast with potential for calibrate +#'Make categorical forecast based on a multi-model forecast with potential for +#'calibrate #' #'@author Bert Van Schaeybroeck, \email{bertvs@meteo.be} -#'@description This function converts a multi-model ensemble forecast -#' into a categorical forecast by giving the probability -#' for each category. Different methods are available to combine -#' the different ensemble forecasting models into -#' probabilistic categorical forecasts. +#'@description This function converts a multi-model ensemble forecast into a +#'categorical forecast by giving the probability for each category. Different +#'methods are available to combine the different ensemble forecasting models +#'into probabilistic categorical forecasts. #' #' See details in ?CST_CategoricalEnsCombination -#'@param fc a multi-dimensional array with named dimensions containing the seasonal forecast experiment data in the element named \code{$data}. The amount of forecasting models is equal to the size of the \code{dataset} dimension of the data array. The amount of members per model may be different. The size of the \code{member} dimension of the data array is equal to the maximum of the ensemble members among the models. Models with smaller ensemble sizes have residual indices of \code{member} dimension in the data array filled with NA values. -#'@param obs a multidimensional array with named dimensions containing the observed data in the element named \code{$data}. -#'@param amt.cat is the amount of categories. Equally-sized quantiles will be calculated based on the amount of categories. -#'@param cat.method method used to produce the categorical forecast, can be either \code{pool}, \code{comb}, \code{mmw} or \code{obs}. The method pool assumes equal weight for all ensemble members while the method comb assumes equal weight for each model. The weighting method is descirbed in Rajagopalan et al. (2002), Robertson et al. (2004) and Van Schaeybroeck and Vannitsem (2019). Finally, the \code{obs} method classifies the observations into the different categories and therefore contains only 0 and 1 values. -#'@param eval.method is the sampling method used, can be either \code{"in-sample"} or \code{"leave-one-out"}. Default value is the \code{"leave-one-out"} cross validation. -#'@param ... other parameters to be passed on to the calibration procedure. +#'@param fc A multi-dimensional array with named dimensions containing the +#' seasonal forecast experiment data in the element named \code{$data}. The +#' amount of forecasting models is equal to the size of the \code{dataset} +#' dimension of the data array. The amount of members per model may be +#' different. The size of the \code{member} dimension of the data array is +#' equal to the maximum of the ensemble members among the models. Models with +#' smaller ensemble sizes have residual indices of \code{member} dimension in +#' the data array filled with NA values. +#'@param obs A multidimensional array with named dimensions containing the +#' observed data in the element named \code{$data}. +#'@param amt.cat Is the amount of categories. Equally-sized quantiles will be +#' calculated based on the amount of categories. +#'@param cat.method Method used to produce the categorical forecast, can be +#' either \code{pool}, \code{comb}, \code{mmw} or \code{obs}. The method pool +#' assumes equal weight for all ensemble members while the method comb assumes +#' equal weight for each model. The weighting method is descirbed in +#' Rajagopalan et al. (2002), Robertson et al. (2004) and Van Schaeybroeck and +#' Vannitsem (2019). Finally, the \code{obs} method classifies the observations +#' into the different categories and therefore contains only 0 and 1 values. +#'@param eval.method Is the sampling method used, can be either +#' \code{"in-sample"} or \code{"leave-one-out"}. Default value is the +#' \code{"leave-one-out"} cross validation. +#'@param ... Other parameters to be passed on to the calibration procedure. #' -#'@return an array containing the categorical forecasts in the element called \code{$data}. The first two dimensions of the returned object are named dataset and member and are both of size one. An additional dimension named category is introduced and is of size amt.cat. +#'@return An array containing the categorical forecasts in the element called +#'\code{$data}. The first two dimensions of the returned object are named +#'dataset and member and are both of size one. An additional dimension named +#'category is introduced and is of size amt.cat. #' -#'@references Rajagopalan, B., Lall, U., & Zebiak, S. E. (2002). Categorical climate forecasts through regularization and optimal combination of multiple GCM ensembles. Monthly Weather Review, 130(7), 1792-1811. -#'@references Robertson, A. W., Lall, U., Zebiak, S. E., & Goddard, L. (2004). Improved combination of multiple atmospheric GCM ensembles for seasonal prediction. Monthly Weather Review, 132(12), 2732-2744. -#'@references Van Schaeybroeck, B., & Vannitsem, S. (2019). Postprocessing of Long-Range Forecasts. In Statistical Postprocessing of Ensemble Forecasts (pp. 267-290). +#'@references Rajagopalan, B., Lall, U., & Zebiak, S. E. (2002). Categorical +#'climate forecasts through regularization and optimal combination of multiple +#'GCM ensembles. Monthly Weather Review, 130(7), 1792-1811. +#'@references Robertson, A. W., Lall, U., Zebiak, S. E., & Goddard, L. (2004). +#'Improved combination of multiple atmospheric GCM ensembles for seasonal +#'prediction. Monthly Weather Review, 132(12), 2732-2744. +#'@references Van Schaeybroeck, B., & Vannitsem, S. (2019). Postprocessing of +#'Long-Range Forecasts. In Statistical Postprocessing of Ensemble Forecasts (pp. 267-290). #' #'@importFrom s2dv InsertDim #'@import abind #'@export - CategoricalEnsCombination <- function (fc, obs, cat.method, eval.method, amt.cat, ...) { if (!all(c("member", "sdate") %in% names(dim(fc)))) { diff --git a/R/CST_DynBiasCorrection.R b/R/CST_DynBiasCorrection.R index f83def23d7ef54bc32a6ce7a6f9191658095454a..db1685b6817f00c7d03c951ed2126dfe221f691c 100644 --- a/R/CST_DynBiasCorrection.R +++ b/R/CST_DynBiasCorrection.R @@ -20,27 +20,27 @@ #'@references Faranda, D., Alvarez-Castro, M.C., Messori, G., Rodriguez, D., #'and Yiou, P. (2019). The hammam effect or how a warm ocean enhances large #'scale atmospheric predictability.Nature Communications, 10(1), 1316. -#'DOI = https://doi.org/10.1038/s41467-019-09305-8 " +#'DOI = \url{https://doi.org/10.1038/s41467-019-09305-8} " #'@references Faranda, D., Gabriele Messori and Pascal Yiou. (2017). #' Dynamical proxies of North Atlantic predictability and extremes. #' Scientific Reports, 7-41278, 2017. #' -#'@param exp an s2v_cube object with the experiment data -#'@param obs an s2dv_cube object with the reference data -#'@param method a character string indicating the method to apply bias -#'correction among these ones: "PTF","RQUANT","QUANT","SSPLIN" -#'@param wetday logical indicating whether to perform wet day correction -#'or not OR a numeric threshold below which all values are set to zero (by -#'default is set to 'FALSE'). -#'@param proxy a character string indicating the proxy for local dimension -#' 'dim' or inverse of persistence 'theta' to apply the dynamical -#' conditioned bias correction method. -#'@param quanti a number lower than 1 indicating the quantile to perform -#'the computation of local dimension and theta -#'@param ncores The number of cores to use in parallel computation +#'@param exp An s2v_cube object with the experiment data. +#'@param obs An s2dv_cube object with the reference data. +#'@param method A character string indicating the method to apply bias +#' correction among these ones: "PTF","RQUANT","QUANT","SSPLIN". +#'@param wetday Logical indicating whether to perform wet day correction +#' or not OR a numeric threshold below which all values are set to zero (by +#' default is set to 'FALSE'). +#'@param proxy A character string indicating the proxy for local dimension +#' 'dim' or inverse of persistence 'theta' to apply the dynamical +#' conditioned bias correction method. +#'@param quanti A number lower than 1 indicating the quantile to perform +#' the computation of local dimension and theta. +#'@param ncores The number of cores to use in parallel computation. #' -#'@return dynbias an s2dvcube object with a bias correction performed -#'conditioned by local dimension 'dim' or inverse of persistence 'theta' +#'@return dynbias An s2dvcube object with a bias correction performed +#'conditioned by local dimension 'dim' or inverse of persistence 'theta'. #' #'@examples #'# example 1: simple data s2dvcube style @@ -111,25 +111,25 @@ CST_DynBiasCorrection<- function(exp, obs, method = 'QUANT', wetday=FALSE, #' Dynamical proxies of North Atlantic predictability and extremes. #' Scientific Reports, 7-41278, 2017. #' -#'@param exp a multidimensional array with named dimensions with the -#'experiment data -#'@param obs a multidimensional array with named dimensions with the -#'observation data -#'@param method a character string indicating the method to apply bias -#'correction among these ones: -#'"PTF","RQUANT","QUANT","SSPLIN" -#'@param wetday logical indicating whether to perform wet day correction -#'or not OR a numeric threshold below which all values are set to zero (by -#'default is set to 'FALSE'). -#'@param proxy a character string indicating the proxy for local dimension -#''dim' or inverse of persistence 'theta' to apply the dynamical conditioned -#'bias correction method. -#'@param quanti a number lower than 1 indicating the quantile to perform the -#'computation of local dimension and theta -#'@param ncores The number of cores to use in parallel computation +#'@param exp A multidimensional array with named dimensions with the +#' experiment data. +#'@param obs A multidimensional array with named dimensions with the +#' observation data. +#'@param method A character string indicating the method to apply bias +#' correction among these ones: +#' "PTF", "RQUANT", "QUANT", "SSPLIN". +#'@param wetday Logical indicating whether to perform wet day correction +#' or not OR a numeric threshold below which all values are set to zero (by +#' default is set to 'FALSE'). +#'@param proxy A character string indicating the proxy for local dimension +#' 'dim' or inverse of persistence 'theta' to apply the dynamical conditioned +#' bias correction method. +#'@param quanti A number lower than 1 indicating the quantile to perform the +#' computation of local dimension and theta. +#'@param ncores The number of cores to use in parallel computation. #' -#'@return a multidimensional array with named dimensions with a bias correction -#'performed conditioned by local dimension 'dim' or inverse of persistence 'theta' +#'@return A multidimensional array with named dimensions with a bias correction +#'performed conditioned by local dimension 'dim' or inverse of persistence 'theta'. #' #'@import multiApply #'@importFrom ClimProjDiags Subset @@ -140,7 +140,7 @@ CST_DynBiasCorrection<- function(exp, obs, method = 'QUANT', wetday=FALSE, #'obsL <- c(rnorm(1:1980),expL[1,,]*1.2) #'dim (obsL) <- c(time = 100,lat = 4, lon = 5) #'dynbias <- DynBiasCorrection(exp = expL, obs = obsL, method='QUANT', -#' proxy= "dim", quanti = 0.6) +#' proxy= "dim", quanti = 0.6) #'@export DynBiasCorrection<- function(exp, obs, method = 'QUANT',wetday=FALSE, proxy = "dim", quanti, ncores = NULL){ diff --git a/R/CST_EnsClustering.R b/R/CST_EnsClustering.R index 6b1f335e96df89b77c6e0ff8371fff2bc93a53ea..52494032d1edf14e7056b1314422ed8d81c470c4 100644 --- a/R/CST_EnsClustering.R +++ b/R/CST_EnsClustering.R @@ -1,104 +1,94 @@ -#' @rdname CST_EnsClustering -#' @title Ensemble clustering +#'@rdname CST_EnsClustering +#'@title Ensemble clustering #' -#' @author Federico Fabiano - ISAC-CNR, \email{f.fabiano@isac.cnr.it} -#' @author Ignazio Giuntoli - ISAC-CNR, \email{i.giuntoli@isac.cnr.it} -#' @author Danila Volpi - ISAC-CNR, \email{d.volpi@isac.cnr.it} -#' @author Paolo Davini - ISAC-CNR, \email{p.davini@isac.cnr.it} -#' @author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} +#'@author Federico Fabiano - ISAC-CNR, \email{f.fabiano@isac.cnr.it} +#'@author Ignazio Giuntoli - ISAC-CNR, \email{i.giuntoli@isac.cnr.it} +#'@author Danila Volpi - ISAC-CNR, \email{d.volpi@isac.cnr.it} +#'@author Paolo Davini - ISAC-CNR, \email{p.davini@isac.cnr.it} +#'@author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} #' -#' @description This function performs a clustering on members/starting dates -#' and returns a number of scenarios, with representative members for each of them. -#' The clustering is performed in a reduced EOF space. +#'@description This function performs a clustering on members/starting dates +#'and returns a number of scenarios, with representative members for each of +#'them. The clustering is performed in a reduced EOF space. #' -#' Motivation: -#' Ensemble forecasts give a probabilistic insight of average weather conditions -#' on extended timescales, i.e. from sub-seasonal to seasonal and beyond. -#' With large ensembles, it is often an advantage to be able to group members -#' according to similar characteristics and to select the most representative member for each cluster. -#' This can be useful to characterize the most probable forecast scenarios in a multi-model -#' (or single model) ensemble prediction. This approach, applied at a regional level, -#' can also be used to identify the subset of ensemble members that best represent the -#' full range of possible solutions for downscaling applications. -#' The choice of the ensemble members is made flexible in order to meet the requirements -#' of specific (regional) climate information products, to be tailored for different regions and user needs. +#'Motivation: +#'Ensemble forecasts give a probabilistic insight of average weather conditions +#'on extended timescales, i.e. from sub-seasonal to seasonal and beyond. +#'With large ensembles, it is often an advantage to be able to group members +#'according to similar characteristics and to select the most representative +#'member for each cluster. This can be useful to characterize the most probable +#'forecast scenarios in a multi-model (or single model) ensemble prediction. +#'This approach, applied at a regional level, can also be used to identify the +#'subset of ensemble members that best represent the full range of possible +#'solutions for downscaling applications. The choice of the ensemble members is +#'made flexible in order to meet the requirements of specific (regional) climate +#'information products, to be tailored for different regions and user needs. #' -#' Description of the tool: -#' EnsClustering is a cluster analysis tool, based on the k-means algorithm, for ensemble predictions. -#' The aim is to group ensemble members according to similar characteristics and -#' to select the most representative member for each cluster. -#' The user chooses which feature of the data is used to group the ensemble members by clustering: -#' time mean, maximum, a certain percentile (e.g., 75% as in the examples below), -#' standard deviation and trend over the time period. For each ensemble member this value -#' is computed at each grid point, obtaining N lat-lon maps, where N is the number of ensemble members. -#' The anomaly is computed subtracting the ensemble mean of these maps to each of the single maps. -#' The anomaly is therefore computed with respect to the ensemble members (and not with respect to the time) -#' and the Empirical Orthogonal Function (EOF) analysis is applied to these anomaly maps. -#' Regarding the EOF analysis, the user can choose either how many Principal Components (PCs) -#' to retain or the percentage of explained variance to keep. After reducing dimensionality via -#' EOF analysis, k-means analysis is applied using the desired subset of PCs. +#'Description of the tool: +#'EnsClustering is a cluster analysis tool, based on the k-means algorithm, for +#'ensemble predictions. The aim is to group ensemble members according to +#'similar characteristics and to select the most representative member for each +#'cluster. The user chooses which feature of the data is used to group the +#'ensemble members by clustering: time mean, maximum, a certain percentile +#'(e.g., 75% as in the examples below), standard deviation and trend over the +#'time period. For each ensemble member this value is computed at each grid +#'point, obtaining N lat-lon maps, where N is the number of ensemble members. +#'The anomaly is computed subtracting the ensemble mean of these maps to each of +#'the single maps. The anomaly is therefore computed with respect to the +#'ensemble members (and not with respect to the time) and the Empirical +#'Orthogonal Function (EOF) analysis is applied to these anomaly maps. Regarding +#'the EOF analysis, the user can choose either how many Principal Components +#'(PCs) to retain or the percentage of explained variance to keep. After +#'reducing dimensionality via EOF analysis, k-means analysis is applied using +#'the desired subset of PCs. #' -#' The major final outputs are the classification in clusters, i.e. which member belongs -#' to which cluster (in k-means analysis the number k of clusters needs to be defined -#' prior to the analysis) and the most representative member for each cluster, -#' which is the closest member to the cluster centroid. -#' Other outputs refer to the statistics of clustering: in the PC space, the minimum and -#' the maximum distance between a member in a cluster and the cluster centroid -#' (i.e. the closest and the furthest member), the intra-cluster standard -#' deviation for each cluster (i.e. how much the cluster is compact). +#'The major final outputs are the classification in clusters, i.e. which member +#'belongs to which cluster (in k-means analysis the number k of clusters needs +#'to be defined prior to the analysis) and the most representative member for +#'each cluster, which is the closest member to the cluster centroid. Other +#'outputs refer to the statistics of clustering: in the PC space, the minimum +#'and the maximum distance between a member in a cluster and the cluster +#'centroid (i.e. the closest and the furthest member), the intra-cluster +#'standard deviation for each cluster (i.e. how much the cluster is compact). #' -#' @param exp An object of the class 's2dv_cube', containing the variables to be analysed. -#' Each data object in the list is expected to have an element named \code{$data} with at least two -#' spatial dimensions named "lon" and "lat", and dimensions "dataset", "member", "ftime", "sdate". -#' @param time_moment Decides the moment to be applied to the time dimension. Can be either 'mean' (time mean), -#' 'sd' (standard deviation along time) or 'perc' (a selected percentile on time). -#' If 'perc' the keyword 'time_percentile' is also used. -#' @param time_percentile Set the percentile in time you want to analyse (used for `time_moment = "perc"). -#' @param numclus Number of clusters (scenarios) to be calculated. -#' If set to NULL the number of ensemble members divided by 10 is used, with a minimum of 2 and a maximum of 8. -#' @param lon_lim List with the two longitude margins in `c(-180,180)` format. -#' @param lat_lim List with the two latitude margins. -#' @param variance_explained variance (percentage) to be explained by the set of EOFs. -#' Defaults to 80. Not used if numpcs is specified. -#' @param numpcs Number of EOFs retained in the analysis (optional). -#' @param cluster_dim Dimension along which to cluster. Typically "member" or "sdate". -#' This can also be a list like c("member", "sdate"). -#' @param time_dim String or character array with name(s) of dimension(s) over which to compute statistics. -#' If omitted c("ftime", "sdate", "time") are searched in this order. -#' @param verbose Logical for verbose output -#' @return A list with elements \code{$cluster} (cluster assigned for each member), -#' \code{$freq} (relative frequency of each cluster), \code{$closest_member} -#' (representative member for each cluster), \code{$repr_field} (list of fields -#' for each representative member), \code{composites} (list of mean fields for each cluster), -#' \code{$lon} (selected longitudes of output fields), -#' \code{$lat} (selected longitudes of output fields). -#' @examples -#'\donttest{ -#' exp <- lonlat_temp$exp -#' # Example 1: Cluster on all start dates, members and models -#' res <- CST_EnsClustering(exp, numclus = 3, -#' cluster_dim = c("member", "dataset", "sdate")) -#' iclus <- res$cluster[2, 1, 3] -#' -#' #print(paste("Cluster of 2. member, 1. dataset, 3. sdate:", iclus)) -#' #print(paste("Frequency (numerosity) of cluster (", iclus, ") :", res$freq[iclus])) -#' s2dv::PlotEquiMap(res$repr_field[iclus, , ], exp$lon, exp$lat, -#' filled.continents = FALSE, -#' toptitle = paste("Representative field of cluster", iclus)) -#' -#' # Example 2: Cluster on members retaining 4 EOFs during -#' # preliminary dimensional reduction -#' res <- CST_EnsClustering(exp, numclus = 3, numpcs = 4, cluster_dim = "member") -#' -#' # Example 3: Cluster on members, retain 80% of variance during -#' # preliminary dimensional reduction -#' res <- CST_EnsClustering(exp, numclus = 3, variance_explained = 80, -#' cluster_dim = "member") -#' -#' # Example 4: Compute percentile in time -#' res <- CST_EnsClustering(exp, numclus = 3, time_percentile = 90, -#' time_moment = "perc", cluster_dim = "member") -#'} +#'@param exp An object of the class 's2dv_cube', containing the variables to be +#' analysed. Each data object in the list is expected to have an element named +#' \code{$data} with at least two spatial dimensions named "lon" and "lat", and +#' dimensions "dataset", "member", "ftime", "sdate". +#'@param time_moment Decides the moment to be applied to the time dimension. Can +#' be either 'mean' (time mean), 'sd' (standard deviation along time) or 'perc' +#' (a selected percentile on time). If 'perc' the keyword 'time_percentile' is +#' also used. +#'@param time_percentile Set the percentile in time you want to analyse (used +#' for `time_moment = "perc"). +#'@param numclus Number of clusters (scenarios) to be calculated. If set to NULL +#' the number of ensemble members divided by 10 is used, with a minimum of 2 +#' and a maximum of 8. +#'@param lon_lim List with the two longitude margins in `c(-180,180)` format. +#'@param lat_lim List with the two latitude margins. +#'@param variance_explained variance (percentage) to be explained by the set of +#' EOFs. Defaults to 80. Not used if numpcs is specified. +#'@param numpcs Number of EOFs retained in the analysis (optional). +#'@param cluster_dim Dimension along which to cluster. Typically "member" or +#' "sdate". This can also be a list like c("member", "sdate"). +#'@param time_dim String or character array with name(s) of dimension(s) over +#' which to compute statistics. If omitted c("ftime", "sdate", "time") are +#' searched in this order. +#'@param verbose Logical for verbose output +#'@return A list with elements \code{$cluster} (cluster assigned for each +#'member), \code{$freq} (relative frequency of each cluster), +#'\code{$closest_member} (representative member for each cluster), +#'\code{$repr_field} (list of fields for each representative member), +#'\code{composites} (list of mean fields for each cluster), \code{$lon} +#'(selected longitudes of output fields), \code{$lat} (selected longitudes of +#'output fields). +#'@examples +#'exp <- lonlat_temp$exp +#'exp$data <- ClimProjDiags::Subset(exp$data, along = c('member', 'lat'), list(1:2, 1:7)) +#'exp$lat <- exp$lat[1:7] +#'# Example 1: Cluster on all start dates, members and models +#'res <- CST_EnsClustering(exp, numclus = 3, +#' cluster_dim = c("sdate")) #' #'@export CST_EnsClustering <- function(exp, time_moment = "mean", numclus = NULL, @@ -120,54 +110,58 @@ CST_EnsClustering <- function(exp, time_moment = "mean", numclus = NULL, return(result) } - -#' @rdname EnsClustering -#' @title Ensemble clustering +#'@rdname EnsClustering +#'@title Ensemble clustering #' -#' @author Federico Fabiano - ISAC-CNR, \email{f.fabiano@isac.cnr.it} -#' @author Ignazio Giuntoli - ISAC-CNR, \email{i.giuntoli@isac.cnr.it} -#' @author Danila Volpi - ISAC-CNR, \email{d.volpi@isac.cnr.it} -#' @author Paolo Davini - ISAC-CNR, \email{p.davini@isac.cnr.it} -#' @author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} +#'@author Federico Fabiano - ISAC-CNR, \email{f.fabiano@isac.cnr.it} +#'@author Ignazio Giuntoli - ISAC-CNR, \email{i.giuntoli@isac.cnr.it} +#'@author Danila Volpi - ISAC-CNR, \email{d.volpi@isac.cnr.it} +#'@author Paolo Davini - ISAC-CNR, \email{p.davini@isac.cnr.it} +#'@author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} #' -#' @description This function performs a clustering on members/starting dates -#' and returns a number of scenarios, with representative members for each of them. -#' The clustering is performed in a reduced EOF space. +#'@description This function performs a clustering on members/starting dates +#'and returns a number of scenarios, with representative members for each of +#'them. The clustering is performed in a reduced EOF space. #' -#' @param data A matrix of dimensions 'dataset member sdate ftime lat lon' containing the variables to be analysed. -#' @param lat Vector of latitudes. -#' @param lon Vector of longitudes. -#' @param time_moment Decides the moment to be applied to the time dimension. Can be either 'mean' (time mean), -#' 'sd' (standard deviation along time) or 'perc' (a selected percentile on time). -#' If 'perc' the keyword 'time_percentile' is also used. -#' @param time_percentile Set the percentile in time you want to analyse (used for `time_moment = "perc"). -#' @param numclus Number of clusters (scenarios) to be calculated. -#' If set to NULL the number of ensemble members divided by 10 is used, with a minimum of 2 and a maximum of 8. -#' @param lon_lim List with the two longitude margins in `c(-180,180)` format. -#' @param lat_lim List with the two latitude margins. -#' @param variance_explained variance (percentage) to be explained by the set of EOFs. -#' Defaults to 80. Not used if numpcs is specified. -#' @param numpcs Number of EOFs retained in the analysis (optional). -#' @param cluster_dim Dimension along which to cluster. Typically "member" or "sdate". -#' This can also be a list like c("member", "sdate"). -#' @param time_dim String or character array with name(s) of dimension(s) over which to compute statistics. -#' If omitted c("ftime", "sdate", "time") are searched in this order. -#' @param verbose Logical for verbose output -#' @return A list with elements \code{$cluster} (cluster assigned for each member), -#' \code{$freq} (relative frequency of each cluster), \code{$closest_member} -#' (representative member for each cluster), \code{$repr_field} (list of fields -#' for each representative member), \code{composites} (list of mean fields for each cluster), -#' \code{$lon} (selected longitudes of output fields), -#' \code{$lat} (selected longitudes of output fields). +#'@param data A matrix of dimensions 'dataset member sdate ftime lat lon' +#' containing the variables to be analysed. +#'@param lat Vector of latitudes. +#'@param lon Vector of longitudes. +#'@param time_moment Decides the moment to be applied to the time dimension. Can +#' be either 'mean' (time mean), 'sd' (standard deviation along time) or 'perc' +#' (a selected percentile on time). If 'perc' the keyword 'time_percentile' is +#' also used. +#'@param time_percentile Set the percentile in time you want to analyse (used +#' for `time_moment = "perc"). +#'@param numclus Number of clusters (scenarios) to be calculated. If set to NULL +#' the number of ensemble members divided by 10 is used, with a minimum of 2 +#' and a maximum of 8. +#'@param lon_lim List with the two longitude margins in `c(-180,180)` format. +#'@param lat_lim List with the two latitude margins. +#'@param variance_explained variance (percentage) to be explained by the set of +#' EOFs. Defaults to 80. Not used if numpcs is specified. +#'@param numpcs Number of EOFs retained in the analysis (optional). +#'@param cluster_dim Dimension along which to cluster. Typically "member" or +#' "sdate". This can also be a list like c("member", "sdate"). +#'@param time_dim String or character array with name(s) of dimension(s) over +#' which to compute statistics. If omitted c("ftime", "sdate", "time") are +#' searched in this order. +#'@param verbose Logical for verbose output +#'@return A list with elements \code{$cluster} (cluster assigned for each member), +#'\code{$freq} (relative frequency of each cluster), \code{$closest_member} +#'(representative member for each cluster), \code{$repr_field} (list of fields for +#'each representative member), \code{composites} (list of mean fields for each +#'cluster), \code{$lon} (selected longitudes of output fields), \code{$lat} +#'(selected longitudes of output fields). +#' +#'@examples +#'exp <- lonlat_temp$exp +#'exp$data <- ClimProjDiags::Subset(exp$data, along = c('member', 'lat'), list(1:5, 1:10)) +#'exp$lat <- exp$lat[1:10] +#'res <- EnsClustering(exp$data, exp$lat, exp$lon, numclus = 2, +#' cluster_dim = c("member", "dataset", "sdate")) #' -#' @examples -#'\donttest{ -#' exp <- lonlat_temp$exp -#' res <- EnsClustering(exp$data, exp$lat, exp$lon, numclus = 3, -#' cluster_dim = c("member", "dataset", "sdate")) -#'} #'@export - EnsClustering <- function(data, lat, lon, time_moment = "mean", numclus = NULL, lon_lim = NULL, lat_lim = NULL, variance_explained = 80, numpcs = NULL, time_percentile = 90, time_dim = NULL, diff --git a/R/CST_MergeDims.R b/R/CST_MergeDims.R index 3bd38a81f97c2a7f59b344e9b9f4a0773d6c1995..39814ecd4f8779485f34747e9686465e5cfb7742 100644 --- a/R/CST_MergeDims.R +++ b/R/CST_MergeDims.R @@ -2,17 +2,22 @@ #' #'@author Nuria Perez-Zanon, \email{nuria.perez@bsc.es} #' -#'@description This function merges two dimensions of the array \code{data} in a 's2dv_cube' object into one. The user can select the dimensions to merge and provide the final name of the dimension. The user can select to remove NA values or keep them. +#'@description This function merges two dimensions of the array \code{data} in a +#''s2dv_cube' object into one. The user can select the dimensions to merge and +#'provide the final name of the dimension. The user can select to remove NA +#'values or keep them. #' -#'@param data a 's2dv_cube' object -#'@param merge_dims a character vector indicating the names of the dimensions to merge -#'@param rename_dim a character string indicating the name of the output dimension. If left at NULL, the first dimension name provided in parameter \code{merge_dims} will be used. -#'@param na.rm a logical indicating if the NA values should be removed or not. +#'@param data An 's2dv_cube' object +#'@param merge_dims A character vector indicating the names of the dimensions to +#' merge. +#'@param rename_dim a character string indicating the name of the output +#' dimension. If left at NULL, the first dimension name provided in parameter +#' \code{merge_dims} will be used. +#'@param na.rm A logical indicating if the NA values should be removed or not. #' #'@import abind #'@importFrom ClimProjDiags Subset #'@examples -#' #'data <- 1 : c(2 * 3 * 4 * 5 * 6 * 7) #'dim(data) <- c(time = 7, lat = 2, lon = 3, monthly = 4, member = 6, #' dataset = 5, var = 1) @@ -27,101 +32,105 @@ #'new_data <- CST_MergeDims(data, merge_dims = c('time', 'monthly'), na.rm = TRUE) #'dim(new_data$data) #'@export -CST_MergeDims <- function(data, merge_dims = c('ftime', 'monthly'), rename_dim = NULL, - na.rm = FALSE) { - if (!inherits(data, 's2dv_cube')) { +CST_MergeDims <- function(data, merge_dims = c('ftime', 'monthly'), + rename_dim = NULL, na.rm = FALSE) { + if (!inherits(data, 's2dv_cube')) { stop("Parameter 'data' must be of the class 's2dv_cube', ", "as output by CSTools::CST_Load.") } - data$data <- MergeDims(data$data, merge_dims = merge_dims, - rename_dim = rename_dim, na.rm = na.rm) - return(data) + data$data <- MergeDims(data$data, merge_dims = merge_dims, + rename_dim = rename_dim, na.rm = na.rm) + return(data) } #'Function to Split Dimension #' #'@author Nuria Perez-Zanon, \email{nuria.perez@bsc.es} #' -#'@description This function merges two dimensions of an array into one. The user can select the dimensions to merge and provide the final name of the dimension. The user can select to remove NA values or keep them. +#'@description This function merges two dimensions of an array into one. The +#'user can select the dimensions to merge and provide the final name of the +#'dimension. The user can select to remove NA values or keep them. #' -#'@param data an n-dimensional array with named dimensions -#'@param merge_dims a character vector indicating the names of the dimensions to merge -#'@param rename_dim a character string indicating the name of the output dimension. If left at NULL, the first dimension name provided in parameter \code{merge_dims} will be used. -#'@param na.rm a logical indicating if the NA values should be removed or not. +#'@param data An n-dimensional array with named dimensions +#'@param merge_dims A character vector indicating the names of the dimensions to +#' merge. +#'@param rename_dim A character string indicating the name of the output +#' dimension. If left at NULL, the first dimension name provided in parameter +#' \code{merge_dims} will be used. +#'@param na.rm A logical indicating if the NA values should be removed or not. #' #'@import abind #'@importFrom ClimProjDiags Subset #'@examples -#' #'data <- 1 : 20 #'dim(data) <- c(time = 10, lat = 2) #'new_data <- MergeDims(data, merge_dims = c('time', 'lat')) #'@export -MergeDims <- function(data, merge_dims = c('time', 'monthly'), rename_dim = NULL, - na.rm = FALSE) { - # check data - if (is.null(data)) { - stop("Parameter 'data' cannot be NULL.") - } - if (is.null(dim(data))) { - stop("Parameter 'data' must have dimensions.") - } - if (is.null(names(dim(data)))) { - stop("Parameter 'data' must have dimension names.") - } - dims <- dim(data) - # check merge_dims - if (is.null(merge_dims)) { - stop("Parameter 'merge_dims' cannot be NULL.") - } - if (!is.character(merge_dims)) { - stop("Parameter 'merge_dims' must be a character vector ", - "indicating the names of the dimensions to be merged.") - } - if (length(merge_dims) > 2) { - warning("Only two dimensions can be merge, only the first two ", - "dimension will be used. To merge further dimensions ", - "consider to use this function multiple times.") - merge_dims <- merge_dims[1 : 2] - } else if (length(merge_dims) < 2) { - stop("Parameter 'merge_dims' must be of length two.") - } - if (is.null(rename_dim)) { - rename_dim <- merge_dims[1] - } - if (length(rename_dim) > 1) { - warning("Parameter 'rename_dim' has length greater than 1 ", - "and only the first element will be used.") - rename_dim <- as.character(rename_dim[1]) - } - if (!any(names(dims) %in% merge_dims)) { - stop("Parameter 'merge_dims' must match with dimension ", - "names in parameter 'data'.") - } - pos1 <- which(names(dims) == merge_dims[1]) - pos2 <- which(names(dims) == merge_dims[2]) - if (length(pos1) == 0 | length(pos2) == 0) { - stop("Parameter 'merge_dims' must match with dimension ", - "names in parameter 'data'.") - } - if (pos1 > pos2) { - pos1 <- pos1 - 1 - } - data <- lapply(1 : dims[pos2], function(x) {Subset(data, along = pos2, - indices = x, drop = 'selected')}) - data <- abind(data, along = pos1) - names(dim(data)) <- names(dims)[-pos2] - if (!is.null(rename_dim)) { - names(dim(data))[pos1] <- rename_dim - } - if (na.rm) { - nas <- which(is.na(Subset(data, along = -pos1, indices = 1))) - if (length(nas) != 0) { - nas <- unlist(lapply(nas, function(x) { - if(all(is.na(Subset(data, along = pos1, - indices = x)))) { - return(x)}})) - data <- Subset(data, along = pos1, indices = -nas) - } +MergeDims <- function(data, merge_dims = c('time', 'monthly'), + rename_dim = NULL, na.rm = FALSE) { + # check data + if (is.null(data)) { + stop("Parameter 'data' cannot be NULL.") + } + if (is.null(dim(data))) { + stop("Parameter 'data' must have dimensions.") + } + if (is.null(names(dim(data)))) { + stop("Parameter 'data' must have dimension names.") + } + dims <- dim(data) + # check merge_dims + if (is.null(merge_dims)) { + stop("Parameter 'merge_dims' cannot be NULL.") + } + if (!is.character(merge_dims)) { + stop("Parameter 'merge_dims' must be a character vector ", + "indicating the names of the dimensions to be merged.") + } + if (length(merge_dims) > 2) { + warning("Only two dimensions can be merge, only the first two ", + "dimension will be used. To merge further dimensions ", + "consider to use this function multiple times.") + merge_dims <- merge_dims[1 : 2] + } else if (length(merge_dims) < 2) { + stop("Parameter 'merge_dims' must be of length two.") + } + if (is.null(rename_dim)) { + rename_dim <- merge_dims[1] + } + if (length(rename_dim) > 1) { + warning("Parameter 'rename_dim' has length greater than 1 ", + "and only the first element will be used.") + rename_dim <- as.character(rename_dim[1]) + } + if (!any(names(dims) %in% merge_dims)) { + stop("Parameter 'merge_dims' must match with dimension ", + "names in parameter 'data'.") + } + pos1 <- which(names(dims) == merge_dims[1]) + pos2 <- which(names(dims) == merge_dims[2]) + if (length(pos1) == 0 | length(pos2) == 0) { + stop("Parameter 'merge_dims' must match with dimension ", + "names in parameter 'data'.") + } + if (pos1 > pos2) { + pos1 <- pos1 - 1 + } + data <- lapply(1:dims[pos2], function(x) {Subset(data, along = pos2, + indices = x, drop = 'selected')}) + data <- abind(data, along = pos1) + names(dim(data)) <- names(dims)[-pos2] + if (!is.null(rename_dim)) { + names(dim(data))[pos1] <- rename_dim + } + if (na.rm) { + nas <- which(is.na(Subset(data, along = -pos1, indices = 1))) + if (length(nas) != 0) { + nas <- unlist(lapply(nas, function(x) { + if(all(is.na(Subset(data, along = pos1, + indices = x)))) { + return(x)}})) + data <- Subset(data, along = pos1, indices = -nas) } -return(data) + } + return(data) } diff --git a/R/CST_MultiEOF.R b/R/CST_MultiEOF.R index 7bdf3698ef65cc569382d5d14061a44517b31e77..a43b7bcfeef0ab1e4faedaa8a2d50489bd028423 100644 --- a/R/CST_MultiEOF.R +++ b/R/CST_MultiEOF.R @@ -1,59 +1,48 @@ -#' @rdname CST_MultiEOF -#' @title EOF analysis of multiple variables +#'@rdname CST_MultiEOF +#'@title EOF analysis of multiple variables #' -#' @author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} -#' @author Paolo Davini - ISAC-CNR, \email{p.davini@isac.cnr.it} +#'@author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} +#'@author Paolo Davini - ISAC-CNR, \email{p.davini@isac.cnr.it} #' -#' @description This function performs EOF analysis over multiple variables, -#' accepting in input a list of CSTools objects. Based on Singular Value Decomposition. For each field the EOFs are computed and the corresponding PCs are standardized (unit variance, zero mean); the minimum number of principal components needed to reach the user-defined variance is retained. The function weights the input data for the latitude cosine square root. - -#' -#' @param datalist A list of objects of the class 's2dv_cube', containing the variables to be analysed. -#' Each data object in the list is expected to have an element named \code{$data} with at least two -#' spatial dimensions named "lon" and "lat", a dimension "ftime" and a dimension "sdate". -#' @param neof_composed Number of composed eofs to return in output -#' @param minvar Minimum variance fraction to be explained in first decomposition -#' @param neof_max Maximum number of single eofs considered in the first decomposition -#' @param lon_lim Vector with longitudinal range limits for the EOF calculation for all input variables -#' @param lat_lim Vector with latitudinal range limits for the EOF calculation for all input variables -#' @return A list with elements \code{$coeff} (an array of time-varying principal component coefficients), -#' \code{$variance} (a matrix of explained variances), -#' \code{eof_pattern} (a matrix of EOF patterns obtained by regression for each variable). -#' @import abind -#' @examples -#' \donttest{ -#' library(zeallot) -#' library(ClimProjDiags) -#' c(exp, obs) %<-% lonlat_temp -#' # Create three datasets (from the members) -#' exp1 <- exp -#' exp2 <- exp -#' exp3 <- exp -#' exp1$data <- Subset(exp$data, along = 2, indices = 1 : 5) -#' exp2$data <- Subset(exp$data, along = 2, indices = 6 : 10) -#' exp3$data <- Subset(exp$data, along = 2, indices = 11 : 15) +#'@description This function performs EOF analysis over multiple variables, +#'accepting in input a list of CSTools objects. Based on Singular Value +#'Decomposition. For each field the EOFs are computed and the corresponding PCs +#'are standardized (unit variance, zero mean); the minimum number of principal +#'components needed to reach the user-defined variance is retained. The function +#'weights the input data for the latitude cosine square root. #' -#' cal <- CST_MultiEOF(list(exp1, exp2, exp3), neof_max=5, neof_composed=2) -#' str(cal) -#' # List of 3 -#' # $ coeff : num [1:3, 1:6, 1:2, 1:5] -0.312 -0.588 0.724 1.202 1.181 ... -#' # $ variance : num [1:2, 1:5] 0.413 0.239 0.352 0.27 0.389 ... -#' # $ eof_pattern: num [1:3, 1:53, 1:22, 1:2, 1:5] -1.47 -0.446 -0.656 -1.534 -0.464 ... -#' dim(cal$coeff) -#' # ftime sdate eof member -#' # 3 6 2 3 +#'@param datalist A list of objects of the class 's2dv_cube', containing the +#' variables to be analysed. Each data object in the list is expected to have +#' an element named \code{$data} with at least two spatial dimensions named +#' "lon" and "lat", a dimension "ftime" and a dimension "sdate". +#'@param neof_composed Number of composed eofs to return in output. +#'@param minvar Minimum variance fraction to be explained in first decomposition. +#'@param neof_max Maximum number of single eofs considered in the first +#' decomposition. +#'@param lon_lim Vector with longitudinal range limits for the EOF calculation +#' for all input variables. +#'@param lat_lim Vector with latitudinal range limits for the EOF calculation +#' for all input variables. +#'@return A list with elements \code{$coeff} (an array of time-varying principal +#'component coefficients), \code{$variance} (a matrix of explained variances), +#'\code{eof_pattern} (a matrix of EOF patterns obtained by regression for each +#'variable). +#'@import abind +#'@examples +#'exp <- lonlat_temp$exp +#'exp$data <- ClimProjDiags::Subset(exp$data, along = c('lat', 'lon'), list(1:4, 1:4)) +#'exp$lat <- exp$lat[1:4] +#'exp$lon <- exp$lon[1:4] +#' +#'# Create three datasets (from the members) +#'exp1 <- exp +#'exp2 <- exp #' -#' cal <- CST_MultiEOF(list(exp1, exp2, exp3) , minvar=0.9) -#' str(cal) -#' # $ coeff : num [1:3, 1:6, 1:5, 1:5] 0.338 0.603 -0.736 -1.191 -1.198 ... -#' # $ variance : num [1:5, 1:5] 0.3903 0.2264 0.1861 0.1032 0.0379 ... -#' # $ eof_pattern: num [1:3, 1:53, 1:22, 1:5, 1:5] 1.477 0.454 0.651 1.541 0.47 ... +#'exp1$data <- ClimProjDiags::Subset(exp$data, along = 2, indices = 1:5) +#'exp2$data <- ClimProjDiags::Subset(exp$data, along = 2, indices = 6:10) #' -#' cal <- CST_MultiEOF(list(exp1, exp2)) -#' cal <- CST_MultiEOF(list(exp1, exp2, exp3), lon_lim=c(5, 30), lat_lim=c(35, 50), neof_composed=3) -#' } -#' @export - +#'cal <- CST_MultiEOF(list(exp1, exp2) , minvar = 0.9) +#'@export CST_MultiEOF <- function(datalist, neof_max = 40, neof_composed = 5, minvar = 0.6, lon_lim = NULL, lat_lim = NULL) { @@ -80,44 +69,60 @@ CST_MultiEOF <- function(datalist, } result <- MultiEOF(exp, datalist[[1]]$lon, datalist[[1]]$lat, - datalist[[1]]$Dates$start, minvar = minvar, - neof_max = neof_max, neof_composed = neof_composed, - lon_lim = lon_lim, lat_lim = lat_lim) + datalist[[1]]$Dates$start, minvar = minvar, + neof_max = neof_max, neof_composed = neof_composed, + lon_lim = lon_lim, lat_lim = lat_lim) return(result) } - -#' @rdname MultiEOF -#' @title EOF analysis of multiple variables starting from an array (reduced version) +#'@rdname MultiEOF +#'@title EOF analysis of multiple variables starting from an array (reduced +#'version) #' -#' @author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} -#' @author Paolo Davini - ISAC-CNR, \email{p.davini@isac.cnr.it} +#'@author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} +#'@author Paolo Davini - ISAC-CNR, \email{p.davini@isac.cnr.it} #' -#' @description This function performs EOF analysis over multiple variables, accepting in input an array with a dimension \code{"var"} for each variable to analyse. Based on Singular Value Decomposition. For each field the EOFs are computed and the corresponding PCs are standardized (unit variance, zero mean); the minimum number of principal components needed to reach the user-defined variance is retained. The function weights the input data for the latitude cosine square root. +#'@description This function performs EOF analysis over multiple variables, +#'accepting in input an array with a dimension \code{"var"} for each variable to +#'analyse. Based on Singular Value Decomposition. For each field the EOFs are +#'computed and the corresponding PCs are standardized (unit variance, zero mean); +#'the minimum number of principal components needed to reach the user-defined +#'variance is retained. The function weights the input data for the latitude +#'cosine square root. #' -#' @param data A multidimensional array with dimension \code{"var"}, -#' containing the variables to be analysed. The other diemnsions follow the same structure as the -#' \code{"exp"} element of a 's2dv_cube' object. -#' @param lon Vector of longitudes. -#' @param lat Vector of latitudes. -#' @param time Vector or matrix of dates in POSIXct format. -#' @param lon_dim String with dimension name of longitudinal coordinate -#' @param lat_dim String with dimension name of latitudinal coordinate -#' @param neof_composed Number of composed eofs to return in output -#' @param minvar Minimum variance fraction to be explained in first decomposition -#' @param neof_max Maximum number of single eofs considered in the first decomposition -#' @param lon_lim Vector with longitudinal range limits for the calculation for all input variables -#' @param lat_lim Vector with latitudinal range limits for the calculation for all input variables -#' @return A list with elements \code{$coeff} (an array of time-varying principal component coefficients), -#' \code{$variance} (a matrix of explained variances), -#' \code{eof_pattern} (a matrix of EOF patterns obtained by regression for each variable). -#' @import multiApply -#' @export - +#'@param data A multidimensional array with dimension \code{"var"}, containing +#' the variables to be analysed. The other diemnsions follow the same structure +#' as the \code{"exp"} element of a 's2dv_cube' object. +#'@param lon Vector of longitudes. +#'@param lat Vector of latitudes. +#'@param time Vector or matrix of dates in POSIXct format. +#'@param lon_dim String with dimension name of longitudinal coordinate. +#'@param lat_dim String with dimension name of latitudinal coordinate. +#'@param neof_composed Number of composed eofs to return in output. +#'@param minvar Minimum variance fraction to be explained in first decomposition. +#'@param neof_max Maximum number of single eofs considered in the first +#' decomposition. +#'@param lon_lim Vector with longitudinal range limits for the calculation for +#' all input variables. +#'@param lat_lim Vector with latitudinal range limits for the calculation for +#' all input variables. +#'@return A list with elements \code{$coeff} (an array of time-varying principal +#'component coefficients), \code{$variance} (a matrix of explained variances), +#'\code{eof_pattern} (a matrix of EOF patterns obtained by regression for each +#'variable). +#'@examples +#'exp <- lonlat_temp$exp +#'exp$data <- ClimProjDiags::Subset(exp$data, c('member', 'lat', 'lon'), list(1:5, 1:4, 1:4)) +#'exp$lon <- exp$lon[1:4] +#'exp$lat <- exp$lat[1:4] +#'dim(exp$data) <- c(dim(exp$data), var = 1) +#'cal <- MultiEOF(data = exp$data, lon = exp$lon, lat = exp$lat, time = exp$Dates$start) +#'@import multiApply +#'@export MultiEOF <- function(data, lon, lat, time, - lon_dim = "lon", lat_dim = "lat", - neof_max = 40, neof_composed = 5, minvar = 0.6, - lon_lim = NULL, lat_lim = NULL) { + lon_dim = "lon", lat_dim = "lat", + neof_max = 40, neof_composed = 5, minvar = 0.6, + lon_lim = NULL, lat_lim = NULL) { # Check/detect time_dim # reorder and group ftime and sdate together at the end in that order @@ -148,20 +153,21 @@ MultiEOF <- function(data, lon, lat, time, return(result) } - -#' Atomic MultiEOF -#' @param field_arr_raw an array of dimension: (n_field, lon, lat, time). -#' where n_field is the number of variables over which to calculate -#' the multi_eofs. -#' @param neof_composed Number of composed eofs to return in output -#' @param minvar Minimum variance fraction to be explained in first decomposition -#' @param neof_max Maximum number of single eofs considered in the first decomposition -#' @param xlim Vector with longitudinal range limits for the calculation -#' @param ylim Vector with latitudinal range limits for the calculation -#' @return A list with elements \code{$coeff} (an array of time-varying principal component coefficients), -#' \code{$variance} (a matrix of explained variances), -#' \code{eof_pattern} (a matrix of EOF patterns obtained by regression for each variable). -#' @noRd +#'Atomic MultiEOF +#'@param field_arr_raw An array of dimension: (n_field, lon, lat, time). +#' where n_field is the number of variables over which to calculate the +#' multi_eofs. +#'@param neof_composed Number of composed eofs to return in output. +#'@param minvar Minimum variance fraction to be explained in first decomposition. +#'@param neof_max Maximum number of single eofs considered in the first +#' decomposition. +#'@param xlim Vector with longitudinal range limits for the calculation. +#'@param ylim Vector with latitudinal range limits for the calculation. +#'@return A list with elements \code{$coeff} (an array of time-varying principal +#'component coefficients), \code{$variance} (a matrix of explained variances), +#'\code{eof_pattern} (a matrix of EOF patterns obtained by regression for each +#'variable). +#'@noRd .multi.eofs <- function(field_arr_raw, lon, lat, time, neof_max = 40, neof_composed = 5, minvar = 0.6, diff --git a/R/CST_MultiMetric.R b/R/CST_MultiMetric.R index 93b7392df34e82eba0cff2090cd4b3ca1675588a..fc8767795e034e1ddbda76b68414f2f1c2455c86 100644 --- a/R/CST_MultiMetric.R +++ b/R/CST_MultiMetric.R @@ -2,20 +2,40 @@ #' #'@author Mishra Niti, \email{niti.mishra@bsc.es} #'@author Perez-Zanon Nuria, \email{nuria.perez@bsc.es} -#'@description This function calculates correlation (Anomaly Correlation Coefficient; ACC), root mean square error (RMS) and the root mean square error skill score (RMSSS) of individual anomaly models and multi-models mean (if desired) with the observations. +#'@description This function calculates correlation (Anomaly Correlation +#'Coefficient; ACC), root mean square error (RMS) and the root mean square error +#'skill score (RMSSS) of individual anomaly models and multi-models mean (if +#'desired) with the observations. #' -#'@param exp an object of class \code{s2dv_cube} as returned by \code{CST_Anomaly} function, containing the anomaly of the seasonal forecast experiments data in the element named \code{$data}. -#'@param obs an object of class \code{s2dv_cube} as returned by \code{CST_Anomaly} function, containing the anomaly of observed data in the element named \code{$data}. -#'@param metric a character string giving the metric for computing the maximum skill. This must be one of the strings 'correlation', 'rms', 'rmsss' and 'rpss'. If 'rpss' is chossen the terciles probabilities are evaluated. -#'@param multimodel a logical value indicating whether a Multi-Model Mean should be computed. -#' -#'@param time_dim name of the temporal dimension where a mean will be applied. It can be NULL, the default value is 'ftime'. -#'@param memb_dim name of the member dimension. It can be NULL, the default value is 'member'. -#'@param sdate_dim name of the start date dimension or a dimension name identifiying the different forecast. It can be NULL, the default value is 'sdate'. -#'@return an object of class \code{s2dv_cube} containing the statistics of the selected metric in the element \code{$data} which is a list of arrays: for the metric requested and others for statistics about its signeificance. The arrays have two dataset dimensions equal to the 'dataset' dimension in the \code{exp$data} and \code{obs$data} inputs. If \code{multimodel} is TRUE, the first position in the first 'nexp' dimension correspons to the Multi-Model Mean. -#'@seealso \code{\link[s2dv]{Corr}}, \code{\link[s2dv]{RMS}}, \code{\link[s2dv]{RMSSS}} and \code{\link{CST_Load}} -#'@references -#'Mishra, N., Prodhomme, C., & Guemas, V. (n.d.). Multi-Model Skill Assessment of Seasonal Temperature and Precipitation Forecasts over Europe, 29-31.\url{https://link.springer.com/article/10.1007/s00382-018-4404-z} +#'@param exp An object of class \code{s2dv_cube} as returned by +#' \code{CST_Anomaly} function, containing the anomaly of the seasonal forecast +#' experiments data in the element named \code{$data}. +#'@param obs An object of class \code{s2dv_cube} as returned by +#' \code{CST_Anomaly} function, containing the anomaly of observed data in the +#' element named \code{$data}. +#'@param metric A character string giving the metric for computing the maximum +#' skill. This must be one of the strings 'correlation', 'rms', 'rmsss' and +#' 'rpss'. If 'rpss' is chossen the terciles probabilities are evaluated. +#'@param multimodel A logical value indicating whether a Multi-Model Mean should +#' be computed. +#'@param time_dim Name of the temporal dimension where a mean will be applied. +#' It can be NULL, the default value is 'ftime'. +#'@param memb_dim Name of the member dimension. It can be NULL, the default +#' value is 'member'. +#'@param sdate_dim Name of the start date dimension or a dimension name +#' identifiying the different forecast. It can be NULL, the default value is +#' 'sdate'. +#'@return An object of class \code{s2dv_cube} containing the statistics of the +#'selected metric in the element \code{$data} which is a list of arrays: for the +#'metric requested and others for statistics about its signeificance. The arrays +#'have two dataset dimensions equal to the 'dataset' dimension in the +#'\code{exp$data} and \code{obs$data} inputs. If \code{multimodel} is TRUE, the +#'first position in the first 'nexp' dimension correspons to the Multi-Model Mean. +#'@seealso \code{\link[s2dv]{Corr}}, \code{\link[s2dv]{RMS}}, +#'\code{\link[s2dv]{RMSSS}} and \code{\link{CST_Load}} +#'@references Mishra, N., Prodhomme, C., & Guemas, V. (n.d.). Multi-Model Skill +#'Assessment of Seasonal Temperature and Precipitation Forecasts over Europe, +#'29-31.\url{https://link.springer.com/article/10.1007/s00382-018-4404-z} #' #'@importFrom s2dv MeanDims Reorder Corr RMS RMSSS InsertDim #'@import abind @@ -23,28 +43,17 @@ #'@import stats #'@import multiApply #'@examples -#'library(zeallot) -#'mod <- 1 : (2 * 3 * 4 * 5 * 6 * 7) -#'dim(mod) <- c(dataset = 2, member = 3, sdate = 4, ftime = 5, lat = 6, lon = 7) -#'obs <- 1 : (1 * 1 * 4 * 5 * 6 * 7) -#'dim(obs) <- c(dataset = 1, member = 1, sdate = 4, ftime = 5, lat = 6, lon = 7) +#'mod <- rnorm(2 * 2 * 4 * 5 * 2 * 2) +#'dim(mod) <- c(dataset = 2, member = 2, sdate = 4, ftime = 5, lat = 2, lon = 2) +#'obs <- rnorm(1 * 1 * 4 * 5 * 2 * 2) +#'dim(obs) <- c(dataset = 1, member = 1, sdate = 4, ftime = 5, lat = 2, lon = 2) #'lon <- seq(0, 30, 5) #'lat <- seq(0, 25, 5) #'exp <- list(data = mod, lat = lat, lon = lon) #'obs <- list(data = obs, lat = lat, lon = lon) #'attr(exp, 'class') <- 's2dv_cube' #'attr(obs, 'class') <- 's2dv_cube' -#'c(ano_exp, ano_obs) %<-% CST_Anomaly(exp = exp, obs = obs, cross = TRUE, memb = TRUE) -#'a <- CST_MultiMetric(exp = ano_exp, obs = ano_obs) -#'str(a) -#'\donttest{ -#'exp <- lonlat_temp$exp -#'obs <- lonlat_temp$obs -#'a <- CST_MultiMetric(exp, obs, metric = 'rpss', multimodel = FALSE) -#'a <- CST_MultiMetric(exp, obs, metric = 'correlation') -#'a <- CST_MultiMetric(exp, obs, metric = 'rms') -#'a <- CST_MultiMetric(exp, obs, metric = 'rmsss') -#'} +#'a <- CST_MultiMetric(exp = exp, obs = obs) #'@export CST_MultiMetric <- function(exp, obs, metric = "correlation", multimodel = TRUE, time_dim = 'ftime', memb_dim = 'member', @@ -58,24 +67,40 @@ CST_MultiMetric <- function(exp, obs, metric = "correlation", multimodel = TRUE, exp$data <- result return(exp) } + #'Multiple Metrics applied in Multiple Model Anomalies #' #'@author Mishra Niti, \email{niti.mishra@bsc.es} #'@author Perez-Zanon Nuria, \email{nuria.perez@bsc.es} -#'@description This function calculates correlation (Anomaly Correlation Coefficient; ACC), root mean square error (RMS) and the root mean square error skill score (RMSSS) of individual anomaly models and multi-models mean (if desired) with the observations on arrays with named dimensions. -#' -#'@param exp a multidimensional array with named dimensions. -#'@param obs a multidimensional array with named dimensions. -#'@param metric a character string giving the metric for computing the maximum skill. This must be one of the strings 'correlation', 'rms' or 'rmsss. -#'@param multimodel a logical value indicating whether a Multi-Model Mean should be computed. +#'@description This function calculates correlation (Anomaly Correlation +#'Coefficient; ACC), root mean square error (RMS) and the root mean square error +#'skill score (RMSSS) of individual anomaly models and multi-models mean (if +#'desired) with the observations on arrays with named dimensions. #' -#'@param time_dim name of the temporal dimension where a mean will be applied. It can be NULL, the default value is 'ftime'. -#'@param memb_dim name of the member dimension. It can be NULL, the default value is 'member'. -#'@param sdate_dim name of the start date dimension or a dimension name identifiying the different forecast. It can be NULL, the default value is 'sdate'. -#'@return a list of arrays containing the statistics of the selected metric in the element \code{$data} which is a list of arrays: for the metric requested and others for statistics about its signeificance. The arrays have two dataset dimensions equal to the 'dataset' dimension in the \code{exp$data} and \code{obs$data} inputs. If \code{multimodel} is TRUE, the greatest position in the first dimension correspons to the Multi-Model Mean. -#'@seealso \code{\link[s2dv]{Corr}}, \code{\link[s2dv]{RMS}}, \code{\link[s2dv]{RMSSS}} and \code{\link{CST_Load}} -#'@references -#'Mishra, N., Prodhomme, C., & Guemas, V. (n.d.). Multi-Model Skill Assessment of Seasonal Temperature and Precipitation Forecasts over Europe, 29-31.\url{https://link.springer.com/article/10.1007/s00382-018-4404-z} +#'@param exp A multidimensional array with named dimensions. +#'@param obs A multidimensional array with named dimensions. +#'@param metric A character string giving the metric for computing the maximum +#' skill. This must be one of the strings 'correlation', 'rms' or 'rmsss. +#'@param multimodel A logical value indicating whether a Multi-Model Mean should +#' be computed. +#'@param time_dim Name of the temporal dimension where a mean will be applied. +#' It can be NULL, the default value is 'ftime'. +#'@param memb_dim Name of the member dimension. It can be NULL, the default +#' value is 'member'. +#'@param sdate_dim Name of the start date dimension or a dimension name +#' identifiying the different forecast. It can be NULL, the default value is +#' 'sdate'. +#'@return A list of arrays containing the statistics of the selected metric in +#'the element \code{$data} which is a list of arrays: for the metric requested +#'and others for statistics about its signeificance. The arrays have two dataset +#'dimensions equal to the 'dataset' dimension in the \code{exp$data} and +#'\code{obs$data} inputs. If \code{multimodel} is TRUE, the greatest position in +#'the first dimension correspons to the Multi-Model Mean. +#'@seealso \code{\link[s2dv]{Corr}}, \code{\link[s2dv]{RMS}}, +#'\code{\link[s2dv]{RMSSS}} and \code{\link{CST_Load}} +#'@references Mishra, N., Prodhomme, C., & Guemas, V. (n.d.). Multi-Model Skill +#'Assessment of Seasonal Temperature and Precipitation Forecasts over Europe, +#'29-31.\url{https://link.springer.com/article/10.1007/s00382-018-4404-z} #' #'@importFrom s2dv MeanDims Reorder Corr RMS RMSSS InsertDim #'@import abind @@ -83,7 +108,11 @@ CST_MultiMetric <- function(exp, obs, metric = "correlation", multimodel = TRUE, #'@import stats #'@import multiApply #'@examples -#'res <- MultiMetric(lonlat_temp$exp$data, lonlat_temp$obs$data) +#'exp <- array(rnorm(2 *2 * 4 * 5 * 2 * 2), +#' dim = c(dataset = 2, member = 2, sdate = 4, ftime = 5, lat = 2, lon = 2)) +#'obs <- array(rnorm(1 * 1 * 4 * 5 * 2 * 2), +#' c(dataset = 1, member = 1, sdate = 4, ftime = 5, lat = 2, lon = 2)) +#'res <- MultiMetric(exp = exp, obs = obs) #'@export MultiMetric <- function(exp, obs, metric = "correlation", multimodel = TRUE, time_dim = 'ftime', memb_dim = 'member', sdate_dim = 'sdate') { diff --git a/R/CST_MultivarRMSE.R b/R/CST_MultivarRMSE.R index 7841a19aa4d2a76093c31fc1c682dacc8fd1c340..6f8d9cad2e969d3a1e4ef496c9686f82c7b2107c 100644 --- a/R/CST_MultivarRMSE.R +++ b/R/CST_MultivarRMSE.R @@ -1,14 +1,26 @@ #'Multivariate Root Mean Square Error (RMSE) #' #'@author Deborah Verfaillie, \email{deborah.verfaillie@bsc.es} -#'@description This function calculates the RMSE from multiple variables, as the mean of each variable's RMSE scaled by its observed standard deviation. Variables can be weighted based on their relative importance (defined by the user). +#'@description This function calculates the RMSE from multiple variables, as the +#'mean of each variable's RMSE scaled by its observed standard deviation. +#'Variables can be weighted based on their relative importance (defined by the +#'user). #' -#'@param exp a list of objects, one for each variable, of class \code{s2dv_cube} as returned by \code{CST_Anomaly} function, containing the anomaly of the seasonal forecast experiment data in the element named \code{$data}. -#'@param obs a list of objects, one for each variable (in the same order than the input in 'exp') of class \code{s2dv_cube} as returned by \code{CST_Anomaly} function, containing the observed anomaly data in the element named \code{$data}. +#'@param exp A list of objects, one for each variable, of class \code{s2dv_cube} +#' as returned by \code{CST_Anomaly} function, containing the anomaly of the +#' seasonal forecast experiment data in the element named \code{$data}. +#'@param obs A list of objects, one for each variable (in the same order than +#' the input in 'exp') of class \code{s2dv_cube} as returned by +#' \code{CST_Anomaly} function, containing the observed anomaly data in the +#' element named \code{$data}. +#'@param weight (optional) A vector of weight values to assign to each variable. +#' If no weights are defined, a value of 1 is assigned to every variable. #' -#'@param weight (optional) a vector of weight values to assign to each variable. If no weights are defined, a value of 1 is assigned to every variable. -#' -#'@return an object of class \code{s2dv_cube} containing the RMSE in the element \code{$data} which is an array with two datset dimensions equal to the 'dataset' dimension in the \code{exp$data} and \code{obs$data} inputs. An array with dimensions: c(number of exp, number of obs, 1 (the multivariate RMSE value), number of lat, number of lon) +#'@return An object of class \code{s2dv_cube} containing the RMSE in the element +#' \code{$data} which is an array with two datset dimensions equal to the +#' 'dataset' dimension in the \code{exp$data} and \code{obs$data} inputs. An +#' array with dimensions: c(number of exp, number of obs, 1 (the multivariate +#' RMSE value), number of lat, number of lon) #' #'@seealso \code{\link[s2dv]{RMS}} and \code{\link{CST_Load}} #'@importFrom s2dv RMS MeanDims @@ -55,13 +67,13 @@ CST_MultivarRMSE <- function(exp, obs, weight = NULL) { } if (!(all(sapply(exp, inherits, 's2dv_cube')))) { - stop("Elements of the list in parameter 'exp' must be of the class ", - "'s2dv_cube', as output by CSTools::CST_Load.") + stop("Elements of the list in parameter 'exp' must be of the class ", + "'s2dv_cube', as output by CSTools::CST_Load.") } if (!(all(sapply(obs, inherits, 's2dv_cube')))) { - stop("Elements of the list in parameter 'obs' must be of the class ", - "'s2dv_cube', as output by CSTools::CST_Load.") + stop("Elements of the list in parameter 'obs' must be of the class ", + "'s2dv_cube', as output by CSTools::CST_Load.") } if (length(exp) != length(obs)) { diff --git a/R/CST_ProxiesAttractor.R b/R/CST_ProxiesAttractor.R index 3839a8961ca8acbec97f435a6749a9bd204a5876..1858b134ed04a938fdc445924023ff2982f721c5 100644 --- a/R/CST_ProxiesAttractor.R +++ b/R/CST_ProxiesAttractor.R @@ -9,32 +9,35 @@ #'@description This function computes two dinamical proxies of the attractor: #'The local dimension (d) and the inverse of the persistence (theta) for an #''s2dv_cube' object. -#'These two parameters will be used as a condition for the computation of dynamical -#'scores to measure predictability and to compute bias correction conditioned by -#'the dynamics with the function DynBiasCorrection -#'Funtion based on the matlab code (davide.faranda@lsce.ipsl.fr) used in +#'These two parameters will be used as a condition for the computation of +#'dynamical scores to measure predictability and to compute bias correction +#'conditioned by the dynamics with the function DynBiasCorrection Function +#'based on the matlab code (davide.faranda@lsce.ipsl.fr) used in #'@references Faranda, D., Alvarez-Castro, M.C., Messori, G., Rodriguez, D., and Yiou, P. (2019). #' The hammam effect or how a warm ocean enhances large scale atmospheric predictability. -#' Nature Communications, 10(1), 1316. DOI = https://doi.org/10.1038/s41467-019-09305-8 " +#' Nature Communications, 10(1), 1316. DOI = \url{https://doi.org/10.1038/s41467-019-09305-8} " #'@references Faranda, D., Gabriele Messori and Pascal Yiou. (2017). #' Dynamical proxies of North Atlantic predictability and extremes. #' Scientific Reports, 7-41278, 2017. #' -#'@param data a s2dv_cube object with the data to create the attractor. Must be a matrix with the timesteps in nrow -#'and the grids in ncol(dat(time,grids) -# -#'@param quanti a number lower than 1 indicating the quantile to perform the computation of local dimension and theta -#' -#'@param ncores The number of cores to use in parallel computation -#' +#'@param data An s2dv_cube object with the data to create the attractor. Must be +#' a matrix with the timesteps in nrow and the grids in ncol(dat(time,grids) +#'@param quanti A number lower than 1 indicating the quantile to perform the +#' computation of local dimension and theta. +#'@param ncores The number of cores to use in parallel computation. #'@return dim and theta -#' #'@examples #'# Example 1: Computing the attractor using simple s2dv data -#'attractor <- CST_ProxiesAttractor(data = lonlat_temp$obs, quanti = 0.6) +#'obs <- rnorm(2 * 3 * 4 * 8 * 8) +#'dim(obs) <- c(dataset = 1, member = 2, sdate = 3, ftime = 4, lat = 8, lon = 8) +#'lon <- seq(10, 13.5, 0.5) +#'lat <- seq(40, 43.5, 0.5) +#'data <- list(data = obs, lon = lon, lat = lat) +#'class(data) <- "s2dv_cube" +#'attractor <- CST_ProxiesAttractor(data = data, quanti = 0.6) #' #'@export -CST_ProxiesAttractor <- function(data, quanti, ncores = NULL){ +CST_ProxiesAttractor <- function(data, quanti, ncores = NULL) { if (!inherits(data, 's2dv_cube')) { stop("Parameter 'data' must be of the class 's2dv_cube', ", "as output by CSTools::CST_Load.") @@ -58,24 +61,25 @@ CST_ProxiesAttractor <- function(data, quanti, ncores = NULL){ #'@description This function computes two dinamical proxies of the attractor: #'The local dimension (d) and the inverse of the persistence (theta). #'These two parameters will be used as a condition for the computation of dynamical -#'scores to measure predictability and to compute bias correction conditioned by +#'scores to measure predictability and to compute bias correction conditioned by #'the dynamics with the function DynBiasCorrection. #'Funtion based on the matlab code (davide.faranda@lsce.ipsl.fr) used in: #'@references Faranda, D., Alvarez-Castro, M.C., Messori, G., Rodriguez, D., and Yiou, P. (2019). #' The hammam effect or how a warm ocean enhances large scale atmospheric predictability. -#' Nature Communications, 10(1), 1316. DOI = https://doi.org/10.1038/s41467-019-09305-8 " +#' Nature Communications, 10(1), 1316. DOI = \url{https://doi.org/10.1038/s41467-019-09305-8} " #'@references Faranda, D., Gabriele Messori and Pascal Yiou. (2017). #' Dynamical proxies of North Atlantic predictability and extremes. #' Scientific Reports, 7-41278, 2017. #' -#'@param data a multidimensional array with named dimensions to create the attractor. It requires a temporal dimension named 'time' and spatial dimensions called 'lat' and 'lon', or 'latitude' and 'longitude' or 'grid'. -#'@param quanti a number lower than 1 indicating the quantile to perform the computation of local dimension and theta +#'@param data A multidimensional array with named dimensions to create the +#' attractor. It requires a temporal dimension named 'time' and spatial +#' dimensions called 'lat' and 'lon', or 'latitude' and 'longitude' or 'grid'. +#'@param quanti A number lower than 1 indicating the quantile to perform the +#' computation of local dimension and theta #'@param ncores The number of cores to use in parallel computation. #' #'@return dim and theta -#' -#'@import multiApply -#' +#' #'@examples #'# Example 1: Computing the attractor using simple data #'# Creating an example of matrix data(time,grids): @@ -87,13 +91,8 @@ CST_ProxiesAttractor <- function(data, quanti, ncores = NULL){ #'layout(matrix(c(1, 3, 2, 3), 2, 2)) #'plot(time, Attractor$dim, xlab = 'time', ylab = 'd', #' main = 'local dimension', type = 'l') -#'plot(time, Attractor$theta, xlab = 'time', ylab = 'theta', main = 'theta') -#'plot(Attractor$dim, Attractor$theta, col = 'blue', -#' main = "Proxies of the Attractor", -#' xlab = "local dimension", ylab = "theta", lwd = 8, 'p') -#' +#'@import multiApply #'@export - ProxiesAttractor <- function(data, quanti, ncores = NULL){ if (is.null(data)) { stop("Parameter 'data' cannot be NULL.") diff --git a/R/CST_QuantileMapping.R b/R/CST_QuantileMapping.R index edb2fb895b4c32e754349a979403ec1e522c067e..612bd94e1c9668d6e395d977fbbf970c60366fe9 100644 --- a/R/CST_QuantileMapping.R +++ b/R/CST_QuantileMapping.R @@ -19,9 +19,9 @@ #'@param window_dim A character string indicating the dimension name where #' samples have been stored. It can be NULL (default) in case all samples are #' used. -#'@param method A character string indicating the method to be used:'PTF', -#' 'DIST','RQUANT','QUANT','SSPLIN'. By default, the empirical quantile mapping -#' 'QUANT' is used. +#'@param method A character string indicating the method to be used:'PTF', +#' 'DIST', 'RQUANT', 'QUANT', 'SSPLIN'. By default, the empirical quantile +#' mapping 'QUANT' is used. #'@param na.rm A logical value indicating if missing values should be removed #' (FALSE by default). #'@param ncores An integer indicating the number of cores for parallel @@ -40,14 +40,13 @@ #'dim(exp$data) <- c(dataset = 1, member = 3, sdate = 5, ftime = 4, #' lat = 3, lon = 2) #'class(exp) <- 's2dv_cube' +#'obs <- NULL #'obs$data <- 101 : c(100 + 1 * 1 * 5 * 4 * 3 * 2) #'dim(obs$data) <- c(dataset = 1, member = 1, sdate = 5, ftime = 4, #' lat = 3, lon = 2) #'class(obs) <- 's2dv_cube' #'res <- CST_QuantileMapping(exp, obs) #' -#'# Use data in package -#'\donttest{ #'exp <- lonlat_temp$exp #'exp$data <- exp$data[, , 1:4, , 1:2, 1:3] #'dim(exp$data) <- c(dataset = 1, member = 15, sdate = 4, ftime = 3, @@ -61,7 +60,6 @@ #'dim(exp_cor$data) <- c(dataset = 1, member = 1, sdate = 2, ftime = 3, #' lat = 2, lon = 3) #'res <- CST_QuantileMapping(exp, obs, exp_cor, window_dim = 'ftime') -#'} #' #'@import qmap #'@import multiApply @@ -128,8 +126,8 @@ CST_QuantileMapping <- function(exp, obs, exp_cor = NULL, sdate_dim = 'sdate', #' samples have been stored. It can be NULL (default) in case all samples are #' used. #'@param method A character string indicating the method to be used: 'PTF', -#' 'DIST','RQUANT','QUANT','SSPLIN'. By default, the empirical quantile mapping -#' 'QUANT' is used. +#' 'DIST', 'RQUANT', 'QUANT', 'SSPLIN'. By default, the empirical quantile +#' mapping 'QUANT' is used. #'@param na.rm A logical value indicating if missing values should be removed #' (FALSE by default). #'@param ncores An integer indicating the number of cores for parallel diff --git a/R/CST_RFSlope.R b/R/CST_RFSlope.R index a8457742cbb16bd66d53830f4fdeb1b9f12d7169..84b49d11b78404548a1f96b4a0a3a04b44088ba6 100644 --- a/R/CST_RFSlope.R +++ b/R/CST_RFSlope.R @@ -1,44 +1,50 @@ -#' @rdname CST_RFSlope -#' @title RainFARM spectral slopes from a CSTools object +#'@rdname CST_RFSlope +#'@title RainFARM spectral slopes from a CSTools object #' -#' @author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} +#'@author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} #' -#' @description This function computes spatial spectral slopes from a CSTools object -#' to be used for RainFARM stochastic precipitation downscaling method and accepts a CSTools object (of the class 's2dv_cube') as input. +#'@description This function computes spatial spectral slopes from a CSTools +#'object to be used for RainFARM stochastic precipitation downscaling method and +#'accepts a CSTools object (of the class 's2dv_cube') as input. #' -#' @param data An object of the class 's2dv_cube', containing the spatial precipitation fields to downscale. -#' The data object is expected to have an element named \code{$data} with at least two -#' spatial dimensions named "lon" and "lat" and one or more dimensions over which -#' to average these slopes, which can be specified by parameter \code{time_dim}. -#' @param kmin First wavenumber for spectral slope (default \code{kmin=1}). -#' @param time_dim String or character array with name(s) of dimension(s) (e.g. "ftime", "sdate", "member" ...) -#' over which to compute spectral slopes. If a character array of dimension names is provided, the spectral slopes -#' will be computed as an average over all elements belonging to those dimensions. -#' If omitted one of c("ftime", "sdate", "time") is searched and the first one with more than one element is chosen. -#' @param ncores is an integer that indicates the number of cores for parallel computations using multiApply function. The default value is one. -#' @return CST_RFSlope() returns spectral slopes using the RainFARM convention -#' (the logarithmic slope of k*|A(k)|^2 where A(k) are the spectral amplitudes). -#' The returned array has the same dimensions as the \code{exp} element of the input object, -#' minus the dimensions specified by \code{lon_dim}, \code{lat_dim} and \code{time_dim}. -#' @import rainfarmr -#' @examples -#' #Example using CST_RFSlope for a CSTools object -#' exp <- 1 : (2 * 3 * 4 * 8 * 8) -#' dim(exp) <- c(dataset = 1, member = 2, sdate = 3, ftime = 4, lat = 8, lon = 8) -#' lon <- seq(10, 13.5, 0.5) -#' dim(lon) <- c(lon = length(lon)) -#' lat <- seq(40, 43.5, 0.5) -#' dim(lat) <- c(lat = length(lat)) -#' data <- list(data = exp, lon = lon, lat = lat) -#' slopes <- CST_RFSlope(data) -#' dim(slopes) -#' # dataset member sdate -#' # 1 2 3 -#' slopes -#' # [,1] [,2] [,3] -#' #[1,] 1.893503 1.893503 1.893503 -#' #[2,] 1.893503 1.893503 1.893503 -#' @export +#'@param data An object of the class 's2dv_cube', containing the spatial +#' precipitation fields to downscale. The data object is expected to have an +#' element named \code{$data} with at least two spatial dimensions named "lon" +#' and "lat" and one or more dimensions over which to average these slopes, +#' which can be specified by parameter \code{time_dim}. +#'@param kmin First wavenumber for spectral slope (default \code{kmin=1}). +#'@param time_dim String or character array with name(s) of dimension(s) (e.g. +#' "ftime", "sdate", "member" ...) over which to compute spectral slopes. If a +#' character array of dimension names is provided, the spectral slopes will be +#' computed as an average over all elements belonging to those dimensions. If +#' omitted one of c("ftime", "sdate", "time") is searched and the first one +#' with more than one element is chosen. +#'@param ncores Is an integer that indicates the number of cores for parallel +#' computations using multiApply function. The default value is one. +#'@return CST_RFSlope() returns spectral slopes using the RainFARM convention +#' (the logarithmic slope of k*|A(k)|^2 where A(k) are the spectral amplitudes). +#' The returned array has the same dimensions as the \code{exp} element of the +#' input object, minus the dimensions specified by \code{lon_dim}, +#' \code{lat_dim} and \code{time_dim}. +#'@import rainfarmr +#'@examples +#'#Example using CST_RFSlope for a CSTools object +#'exp <- 1 : (2 * 3 * 4 * 8 * 8) +#'dim(exp) <- c(dataset = 1, member = 2, sdate = 3, ftime = 4, lat = 8, lon = 8) +#'lon <- seq(10, 13.5, 0.5) +#'dim(lon) <- c(lon = length(lon)) +#'lat <- seq(40, 43.5, 0.5) +#'dim(lat) <- c(lat = length(lat)) +#'data <- list(data = exp, lon = lon, lat = lat) +#'slopes <- CST_RFSlope(data) +#'dim(slopes) +#'# dataset member sdate +#'# 1 2 3 +#'slopes +#'# [,1] [,2] [,3] +#'#[1,] 1.893503 1.893503 1.893503 +#'#[2,] 1.893503 1.893503 1.893503 +#'@export CST_RFSlope <- function(data, kmin = 1, time_dim = NULL, ncores = 1) { slopes <- RFSlope(data$data, kmin, time_dim, @@ -47,57 +53,58 @@ CST_RFSlope <- function(data, kmin = 1, time_dim = NULL, ncores = 1) { return(slopes) } -#' @rdname RFSlope -#' @title RainFARM spectral slopes from an array (reduced version) +#'@rdname RFSlope +#'@title RainFARM spectral slopes from an array (reduced version) #' -#' @author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} +#'@author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} #' -#' @description This function computes spatial spectral slopes from an array, -#' to be used for RainFARM stochastic precipitation downscaling method. +#'@description This function computes spatial spectral slopes from an array, +#'to be used for RainFARM stochastic precipitation downscaling method. #' -#' @param data Array containing the spatial precipitation fields to downscale. -#' The input array is expected to have at least two dimensions named "lon" and "lat" by default -#' (these default names can be changed with the \code{lon_dim} and \code{lat_dim} parameters) -#' and one or more dimensions over which to average the slopes, -#' which can be specified by parameter \code{time_dim}. -#' @param kmin First wavenumber for spectral slope (default \code{kmin=1}). -#' @param time_dim String or character array with name(s) of dimension(s) -#' (e.g. "ftime", "sdate", "member" ...) over which to compute spectral slopes. -#' If a character array of dimension names is provided, the spectral slopes -#' will be computed as an average over all elements belonging to those dimensions. -#' If omitted one of c("ftime", "sdate", "time") is searched and the first one -#' with more than one element is chosen. -#' @param lon_dim Name of lon dimension ("lon" by default). -#' @param lat_dim Name of lat dimension ("lat" by default). -#' @param ncores is an integer that indicates the number of cores for parallel computations using multiApply function. The default value is one. +#'@param data Array containing the spatial precipitation fields to downscale. +#' The input array is expected to have at least two dimensions named "lon" and +#' "lat" by default (these default names can be changed with the \code{lon_dim} +#' and \code{lat_dim} parameters) and one or more dimensions over which to +#' average the slopes, which can be specified by parameter \code{time_dim}. +#'@param kmin First wavenumber for spectral slope (default \code{kmin=1}). +#'@param time_dim String or character array with name(s) of dimension(s) +#' (e.g. "ftime", "sdate", "member" ...) over which to compute spectral slopes. +#' If a character array of dimension names is provided, the spectral slopes +#' will be computed as an average over all elements belonging to those dimensions. +#' If omitted one of c("ftime", "sdate", "time") is searched and the first one +#' with more than one element is chosen. +#'@param lon_dim Name of lon dimension ("lon" by default). +#'@param lat_dim Name of lat dimension ("lat" by default). +#'@param ncores is an integer that indicates the number of cores for parallel +#' computations using multiApply function. The default value is one. #' -#' @return RFSlope() returns spectral slopes using the RainFARM convention -#' (the logarithmic slope of k*|A(k)|^2 where A(k) are the spectral amplitudes). -#' The returned array has the same dimensions as the input array, -#' minus the dimensions specified by \code{lon_dim}, \code{lat_dim} and \code{time_dim}. -#' @import multiApply -#' @import rainfarmr -#' @importFrom ClimProjDiags Subset -#' @export -#' @examples -#' # Example for the 'reduced' RFSlope function -#' # Create a test array with dimension 8x8 and 20 timesteps, -#' # 3 starting dates and 20 ensemble members. -#' pr <- 1:(4*3*8*8*20) -#' dim(pr) <- c(ensemble = 4, sdate = 3, lon = 8, lat = 8, ftime = 20) +#'@return RFSlope() returns spectral slopes using the RainFARM convention +#'(the logarithmic slope of k*|A(k)|^2 where A(k) are the spectral amplitudes). +#'The returned array has the same dimensions as the input array, +#'minus the dimensions specified by \code{lon_dim}, \code{lat_dim} and \code{time_dim}. +#'@import multiApply +#'@import rainfarmr +#'@importFrom ClimProjDiags Subset +#'@examples +#'# Example for the 'reduced' RFSlope function +#'# Create a test array with dimension 8x8 and 20 timesteps, +#'# 3 starting dates and 20 ensemble members. +#'pr <- 1:(4*3*8*8*20) +#'dim(pr) <- c(ensemble = 4, sdate = 3, lon = 8, lat = 8, ftime = 20) #' -#' # Compute the spectral slopes ignoring the wavenumber -#' # corresponding to the largest scale (the box) -#' slopes <- RFSlope(pr, kmin=2) -#' dim(slopes) -#' # ensemble sdate -#' # 4 3 -#' slopes -#' # [,1] [,2] [,3] -#' #[1,] 1.893503 1.893503 1.893503 -#' #[2,] 1.893503 1.893503 1.893503 -#' #[3,] 1.893503 1.893503 1.893503 -#' #[4,] 1.893503 1.893503 1.893503 +#'# Compute the spectral slopes ignoring the wavenumber +#'# corresponding to the largest scale (the box) +#'slopes <- RFSlope(pr, kmin=2) +#'dim(slopes) +#'# ensemble sdate +#'# 4 3 +#'slopes +#'# [,1] [,2] [,3] +#'#[1,] 1.893503 1.893503 1.893503 +#'#[2,] 1.893503 1.893503 1.893503 +#'#[3,] 1.893503 1.893503 1.893503 +#'#[4,] 1.893503 1.893503 1.893503 +#'@export RFSlope <- function(data, kmin = 1, time_dim = NULL, lon_dim = "lon", lat_dim = "lat", ncores = 1) { if (length(ncores) > 1) { @@ -158,12 +165,12 @@ RFSlope <- function(data, kmin = 1, time_dim = NULL, return(slopes = result) } -#' Atomic RFSlope -#' @param pr precipitation array to downscale with dims (lon, lat, time). -#' @param kmin first wavenumber for spectral slope (default kmin=1). -#' @return .RFSlope returns a scalar spectral slope using the RainFARM convention -#' (the logarithmic slope of k*|A(k)|^2 where A(k) is the spectral amplitude). -#' @noRd +#'Atomic RFSlope +#'@param pr precipitation array to downscale with dims (lon, lat, time). +#'@param kmin first wavenumber for spectral slope (default kmin=1). +#'@return .RFSlope returns a scalar spectral slope using the RainFARM convention +#'(the logarithmic slope of k*|A(k)|^2 where A(k) is the spectral amplitude). +#'@noRd .RFSlope <- function(pr, kmin) { if (any(is.na(pr))) { diff --git a/R/CST_RFTemp.R b/R/CST_RFTemp.R index cebac85aa555252b19ba156d7d2d4e2a60f946a3..85f293a7936043db765a4199faef93655ec72056 100644 --- a/R/CST_RFTemp.R +++ b/R/CST_RFTemp.R @@ -1,70 +1,70 @@ -#' @rdname CST_RFTemp -#' @title Temperature downscaling of a CSTools object using lapse rate -#' correction or a reference field -#' @author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} -#' @description This function implements a simple lapse rate correction of a -#' temperature field (an object of class 's2dv_cube' as provided by -#' `CST_Load`) as input. -#' The input lon grid must be increasing (but can be modulo 360). -#' The input lat grid can be irregularly spaced (e.g. a Gaussian grid) -#' The output grid can be irregularly spaced in lon and/or lat. -#' @references Method described in ERA4CS MEDSCOPE milestone M3.2: -#' High-quality climate prediction data available to WP4 -#' [https://www.medscope-project.eu/the-project/deliverables-reports/]([https://www.medscope-project.eu/the-project/deliverables-reports/) -#' and in H2020 ECOPOTENTIAL Deliverable No. 8.1: -#' High resolution (1-10 km) climate, land use and ocean change scenarios -#' [https://www.ecopotential-project.eu/images/ecopotential/documents/D8.1.pdf](https://www.ecopotential-project.eu/images/ecopotential/documents/D8.1.pdf) -#' @param data An object of the class 's2dv_cube' as returned by `CST_Load`, -#' containing the temperature fields to downscale. -#' The data object is expected to have an element named \code{$data} -#' with at least two spatial dimensions named "lon" and "lat". -#' (these default names can be changed with the \code{lon_dim} and -#' \code{lat_dim} parameters) -#' @param oro An object of the class 's2dv_cube' as returned by `CST_Load`, -#' containing fine scale orography (in meters). -#' The destination downscaling area must be contained in the orography field. -#' @param xlim vector with longitude bounds for downscaling; -#' the full input field is downscaled if `xlim` and `ylim` are not specified. -#' @param ylim vector with latitude bounds for downscaling -#' @param lapse float with environmental lapse rate -#' @param lon_dim string with name of longitude dimension -#' @param lat_dim string with name of latitude dimension -#' @param time_dim a vector of character string indicating the name of temporal dimension. By default, it is set to NULL and it considers "ftime", "sdate" and "time" as temporal dimensions. -#' @param verbose logical if to print diagnostic output -#' @param nolapse logical, if true `oro` is interpreted as a fine-scale -#' climatology and used directly for bias correction -#' @param compute_delta logical if true returns only a delta to be used for -#' out-of-sample forecasts. Returns an object of the class 's2dv_cube', -#' containing a delta. Activates `nolapse = TRUE`. -#' @param delta An object of the class 's2dv_cube', containing a delta -#' to be applied to the downscaled input data. Activates `nolapse = TRUE`. -#' The grid of this object must coincide with that of the required output. -#' @param method string indicating the method used for interpolation: -#' "nearest" (nearest neighbours followed by smoothing with a circular -#' uniform weights kernel), "bilinear" (bilinear interpolation) -#' The two methods provide similar results, but nearest is slightly better -#' provided that the fine-scale grid is correctly centered as a subdivision -#' of the large-scale grid -#' @return CST_RFTemp() returns a downscaled CSTools object -#' (i.e., of the class 's2dv_cube'). -#' @export -#' @import multiApply -#' @examples -#' # Generate simple synthetic data and downscale by factor 4 -#' t <- rnorm(7 * 6 * 2 * 3 * 4)*10 + 273.15 + 10 -#' dim(t) <- c(dataset = 1, member = 2, sdate = 3, ftime = 4, lat = 6, lon = 7) -#' lon <- seq(3, 9, 1) -#' lat <- seq(42, 47, 1) -#' exp <- list(data = t, lat = lat, lon = lon) -#' attr(exp, 'class') <- 's2dv_cube' -#' o <- runif(29*29)*3000 -#' dim(o) <- c(lat = 29, lon = 29) -#' lon <- seq(3, 10, 0.25) -#' lat <- seq(41, 48, 0.25) -#' oro <- list(data = o, lat = lat, lon = lon) -#' attr(oro, 'class') <- 's2dv_cube' -#' res <- CST_RFTemp(exp, oro, xlim=c(4,8), ylim=c(43, 46), lapse=6.5) - +#'@rdname CST_RFTemp +#'@title Temperature downscaling of a CSTools object using lapse rate +#'correction or a reference field +#'@author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} +#'@description This function implements a simple lapse rate correction of a +#'temperature field (an object of class 's2dv_cube' as provided by +#'`CST_Load`) as input. +#'The input lon grid must be increasing (but can be modulo 360). +#'The input lat grid can be irregularly spaced (e.g. a Gaussian grid) +#'The output grid can be irregularly spaced in lon and/or lat. +#'@references Method described in ERA4CS MEDSCOPE milestone M3.2: +#'High-quality climate prediction data available to WP4 here: +#'\url{https://www.medscope-project.eu/the-project/deliverables-reports/} +#'and in H2020 ECOPOTENTIAL Deliverable No. 8.1: +#'High resolution (1-10 km) climate, land use and ocean change scenarios available +#'here: \url{https://www.ecopotential-project.eu/images/ecopotential/documents/D8.1.pdf} +#'@param data An object of the class 's2dv_cube' as returned by `CST_Load`, +#' containing the temperature fields to downscale. The data object is expected +#' to have an element named \code{$data} with at least two spatial dimensions +#' named "lon" and "lat". (these default names can be changed with the +#' \code{lon_dim} and \code{lat_dim} parameters). +#'@param oro An object of the class 's2dv_cube' as returned by `CST_Load`, +#' containing fine scale orography (in meters). The destination downscaling +#' area must be contained in the orography field. +#'@param xlim Vector with longitude bounds for downscaling; the full input +#' field is downscaled if `xlim` and `ylim` are not specified. +#'@param ylim Vector with latitude bounds for downscaling +#'@param lapse Float with environmental lapse rate +#'@param lon_dim String with name of longitude dimension +#'@param lat_dim String with name of latitude dimension +#'@param time_dim A vector of character string indicating the name of temporal +#' dimension. By default, it is set to NULL and it considers "ftime", "sdate" +#' and "time" as temporal dimensions. +#'@param verbose Logical if to print diagnostic output. +#'@param nolapse Logical, if true `oro` is interpreted as a fine-scale +#' climatology and used directly for bias correction. +#'@param compute_delta Logical if true returns only a delta to be used for +#' out-of-sample forecasts. Returns an object of the class 's2dv_cube', +#' containing a delta. Activates `nolapse = TRUE`. +#'@param delta An object of the class 's2dv_cube', containing a delta +#' to be applied to the downscaled input data. Activates `nolapse = TRUE`. +#' The grid of this object must coincide with that of the required output. +#'@param method String indicating the method used for interpolation: +#' "nearest" (nearest neighbours followed by smoothing with a circular +#' uniform weights kernel), "bilinear" (bilinear interpolation) +#' The two methods provide similar results, but nearest is slightly better +#' provided that the fine-scale grid is correctly centered as a subdivision +#' of the large-scale grid. +#'@return CST_RFTemp() returns a downscaled CSTools object (i.e., of the class +#''s2dv_cube'). +#'@import multiApply +#'@examples +#'# Generate simple synthetic data and downscale by factor 4 +#'t <- rnorm(7 * 6 * 2 * 3 * 4)*10 + 273.15 + 10 +#'dim(t) <- c(dataset = 1, member = 2, sdate = 3, ftime = 4, lat = 6, lon = 7) +#'lon <- seq(3, 9, 1) +#'lat <- seq(42, 47, 1) +#'exp <- list(data = t, lat = lat, lon = lon) +#'attr(exp, 'class') <- 's2dv_cube' +#'o <- runif(29*29)*3000 +#'dim(o) <- c(lat = 29, lon = 29) +#'lon <- seq(3, 10, 0.25) +#'lat <- seq(41, 48, 0.25) +#'oro <- list(data = o, lat = lat, lon = lon) +#'attr(oro, 'class') <- 's2dv_cube' +#'res <- CST_RFTemp(exp, oro, xlim=c(4,8), ylim=c(43, 46), lapse=6.5) +#'@export CST_RFTemp <- function(data, oro, xlim = NULL, ylim = NULL, lapse = 6.5, lon_dim = "lon", lat_dim = "lat", time_dim = NULL, nolapse = FALSE, verbose = FALSE, compute_delta = FALSE, @@ -98,71 +98,70 @@ CST_RFTemp <- function(data, oro, xlim = NULL, ylim = NULL, lapse = 6.5, return(data) } -#' @rdname RFTemp -#' @title Temperature downscaling of a CSTools object using lapse rate -#' correction (reduced version) -#' @author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} -#' @description This function implements a simple lapse rate correction of a -#' temperature field (a multidimensional array) as input. -#' The input lon grid must be increasing (but can be modulo 360). -#' The input lat grid can be irregularly spaced (e.g. a Gaussian grid) -#' The output grid can be irregularly spaced in lon and/or lat. -#' @references Method described in ERA4CS MEDSCOPE milestone M3.2: -#' High-quality climate prediction data available to WP4 -#' [https://www.medscope-project.eu/the-project/deliverables-reports/]([https://www.medscope-project.eu/the-project/deliverables-reports/) -#' and in H2020 ECOPOTENTIAL Deliverable No. 8.1: -#' High resolution (1-10 km) climate, land use and ocean change scenarios -#' [https://www.ecopotential-project.eu/images/ecopotential/documents/D8.1.pdf](https://www.ecopotential-project.eu/images/ecopotential/documents/D8.1.pdf) -#' @param data Temperature array to downscale. -#' The input array is expected to have at least two dimensions named -#' "lon" and "lat" by default -#' (these default names can be changed with the \code{lon_dim} and -#' \code{lat_dim} parameters) -#' @param lon Vector or array of longitudes. -#' @param lat Vector or array of latitudes. -#' @param lonoro Vector or array of longitudes corresponding to the fine orography. -#' @param latoro Vector or array of latitudes corresponding to the fine orography. -#' @param oro Array containing fine-scale orography (in m) -#' The destination downscaling area must be contained in the orography field. -#' @param xlim vector with longitude bounds for downscaling; -#' the full input field is downscaled if `xlim` and `ylim` are not specified. -#' @param ylim vector with latitude bounds for downscaling -#' @param lapse float with environmental lapse rate -#' @param lon_dim string with name of longitude dimension -#' @param lat_dim string with name of latitude dimension -#' @param time_dim a vector of character string indicating the name of temporal dimension. By default, it is set to NULL and it considers "ftime", "sdate" and "time" as temporal dimensions. -#' @param verbose logical if to print diagnostic output -#' @param nolapse logical, if true `oro` is interpreted as a -#' fine-scale climatology and used directly for bias correction -#' @param compute_delta logical if true returns only a delta to be used for -#' out-of-sample forecasts. -#' @param delta matrix containing a delta to be applied to the downscaled -#' input data. The grid of this matrix is supposed to be same as that of -#' the required output field -#' @param method string indicating the method used for interpolation: -#' "nearest" (nearest neighbours followed by smoothing with a circular -#' uniform weights kernel), "bilinear" (bilinear interpolation) -#' The two methods provide similar results, but nearest is slightly better -#' provided that the fine-scale grid is correctly centered as a subdivision -#' of the large-scale grid -#' @return CST_RFTemp() returns a downscaled CSTools object -#' @return RFTemp() returns a list containing the fine-scale -#' longitudes, latitudes and the downscaled fields. -#' @export -#' @import multiApply -#' @examples -#' # Generate simple synthetic data and downscale by factor 4 -#' t <- rnorm(7 * 6 * 4 * 3) * 10 + 273.15 + 10 -#' dim(t) <- c(sdate = 3, ftime = 4, lat = 6, lon = 7) -#' lon <- seq(3, 9, 1) -#' lat <- seq(42, 47, 1) -#' o <- runif(29 * 29) * 3000 -#' dim(o) <- c(lat = 29, lon = 29) -#' lono <- seq(3, 10, 0.25) -#' lato <- seq(41, 48, 0.25) -#' res <- RFTemp(t, lon, lat, o, lono, lato, xlim = c(4, 8), ylim = c(43, 46), -#' lapse = 6.5) - +#'@rdname RFTemp +#'@title Temperature downscaling of a CSTools object using lapse rate +#'correction (reduced version) +#'@author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} +#'@description This function implements a simple lapse rate correction of a +#'temperature field (a multidimensional array) as input. +#'The input lon grid must be increasing (but can be modulo 360). +#'The input lat grid can be irregularly spaced (e.g. a Gaussian grid) +#'The output grid can be irregularly spaced in lon and/or lat. +#'@references Method described in ERA4CS MEDSCOPE milestone M3.2: +#'High-quality climate prediction data available to WP4 here: +#'\ url{https://www.medscope-project.eu/the-project/deliverables-reports/} +#'and in H2020 ECOPOTENTIAL Deliverable No. 8.1: +#'High resolution (1-10 km) climate, land use and ocean change scenarios here: +#'\url{https://www.ecopotential-project.eu/images/ecopotential/documents/D8.1.pdf}. +#'@param data Temperature array to downscale. The input array is expected to +#' have at least two dimensions named "lon" and "lat" by default (these default +#' names can be changed with the \code{lon_dim} and \code{lat_dim} parameters). +#'@param lon Vector or array of longitudes. +#'@param lat Vector or array of latitudes. +#'@param lonoro Vector or array of longitudes corresponding to the fine orography. +#'@param latoro Vector or array of latitudes corresponding to the fine orography. +#'@param oro Array containing fine-scale orography (in m). The destination +#' downscaling area must be contained in the orography field. +#'@param xlim Vector with longitude bounds for downscaling; the full input field +#' is downscaled if `xlim` and `ylim` are not specified. +#'@param ylim Vector with latitude bounds for downscaling. +#'@param lapse Float with environmental lapse rate. +#'@param lon_dim String with name of longitude dimension. +#'@param lat_dim String with name of latitude dimension. +#'@param time_dim A vector of character string indicating the name of temporal +#' dimension. By default, it is set to NULL and it considers "ftime", "sdate" +#' and "time" as temporal dimensions. +#'@param verbose Logical if to print diagnostic output. +#'@param nolapse Logical, if true `oro` is interpreted as a fine-scale +#' climatology and used directly for bias correction. +#'@param compute_delta Logical if true returns only a delta to be used for +#' out-of-sample forecasts. +#'@param delta Matrix containing a delta to be applied to the downscaled +#' input data. The grid of this matrix is supposed to be same as that of +#' the required output field. +#'@param method String indicating the method used for interpolation: +#' "nearest" (nearest neighbours followed by smoothing with a circular +#' uniform weights kernel), "bilinear" (bilinear interpolation) +#' The two methods provide similar results, but nearest is slightly better +#' provided that the fine-scale grid is correctly centered as a subdivision +#' of the large-scale grid. +#'@return CST_RFTemp() returns a downscaled CSTools object. +#'@return RFTemp() returns a list containing the fine-scale +#'longitudes, latitudes and the downscaled fields. +#'@import multiApply +#'@examples +#'# Generate simple synthetic data and downscale by factor 4 +#'t <- rnorm(7 * 6 * 4 * 3) * 10 + 273.15 + 10 +#'dim(t) <- c(sdate = 3, ftime = 4, lat = 6, lon = 7) +#'lon <- seq(3, 9, 1) +#'lat <- seq(42, 47, 1) +#'o <- runif(29 * 29) * 3000 +#'dim(o) <- c(lat = 29, lon = 29) +#'lono <- seq(3, 10, 0.25) +#'lato <- seq(41, 48, 0.25) +#'res <- RFTemp(t, lon, lat, o, lono, lato, xlim = c(4, 8), ylim = c(43, 46), +#' lapse = 6.5) +#'@export RFTemp <- function(data, lon, lat, oro, lonoro, latoro, xlim = NULL, ylim = NULL, lapse = 6.5, lon_dim = "lon", lat_dim = "lat", time_dim = NULL, @@ -214,42 +213,43 @@ RFTemp <- function(data, lon, lat, oro, lonoro, latoro, return(result) } -#' Lapse-rate temperature correction downscaling +#'Lapse-rate temperature correction downscaling #' -#' @description Downscales a temperature field using a lapse-rate -#' correction based on a reference orography. Time-averaging is done on all -#' dimensions after the first two. -#' @author Jost von Hardenberg, \email{j.vonhardenberg@isac.cnr.it} -#' @param lon vector of input longitudes -#' @param lat vector of input latitudes -#' @param t matrix of input temperature data -#' @param lono vector of orography longitudes -#' @param lato vector of orography latitudes -#' @param oro matrix of topographical elevations (in meters) -#' The destination downscaling area must be contained in the orography field. -#' @param xlim vector of longitude bounds; the full input field is downscaled if `xlim` and `ylim` are not specified. -#' @param ylim vector of latitude bounds -#' @param radius smoothing radius expressed in longitude units -#' (default is half a large-scale pixel) -#' @param lapse environmental lapse rate (in K/Km) -#' @param nolapse logical, if true `oro` is interpreted as a fine-scale -#' climatology and used directly for bias correction -#' @param compute_delta logical if true returns only a delta to be used for -#' out-of-sample forecasts. -#' @param delta matrix containing a delta to be applied to the input data. -#' The grid of this matrix is supposed to be same as -#' that of the required output field -#' @param verbose logical if to print diagnostic output -#' @return A downscaled temperature matrix -#' @examples -#' lon = 5:20 -#' lat = 35:40 -#' t = runif(16 * 6); dim(t) = c(16, 6) -#' lono = seq(5, 20, 0.1) -#' lato = seq(35, 40, 0.1) -#' o = runif(151 * 51) * 2000; dim(o) = c(151, 51) -#' td = .downscalet(t, lon, lat, o, lono, lato, c(8, 12), c(36, 38)) -#' @noRd +#'@description Downscales a temperature field using a lapse-rate +#'correction based on a reference orography. Time-averaging is done on all +#'dimensions after the first two. +#'@author Jost von Hardenberg, \email{j.vonhardenberg@isac.cnr.it} +#'@param lon Vector of input longitudes. +#'@param lat Vector of input latitudes. +#'@param t Matrix of input temperature data. +#'@param lono Vector of orography longitudes. +#'@param lato Vector of orography latitudes. +#'@param oro Matrix of topographical elevations (in meters). The destination +#' downscaling area must be contained in the orography field. +#'@param xlim Vector of longitude bounds; the full input field is downscaled if +#' `xlim` and `ylim` are not specified. +#'@param ylim Vector of latitude bounds. +#'@param radius Smoothing radius expressed in longitude units (default is half a +#' large-scale pixel). +#'@param lapse Environmental lapse rate (in K/Km). +#'@param nolapse Logical, if true `oro` is interpreted as a fine-scale +#' climatology and used directly for bias correction. +#'@param compute_delta Logical if true returns only a delta to be used for +#' out-of-sample forecasts. +#'@param delta Matrix containing a delta to be applied to the input data. +#' The grid of this matrix is supposed to be same as that of the required +#' output field. +#'@param verbose Logical if to print diagnostic output. +#'@return A downscaled temperature matrix. +#'@examples +#'lon = 5:20 +#'lat = 35:40 +#'t = runif(16 * 6); dim(t) = c(16, 6) +#'lono = seq(5, 20, 0.1) +#'lato = seq(35, 40, 0.1) +#'o = runif(151 * 51) * 2000; dim(o) = c(151, 51) +#'td = .downscalet(t, lon, lat, o, lono, lato, c(8, 12), c(36, 38)) +#'@noRd .downscalet <- function(t, lon, lat, oro, lono, lato, xlim = NULL, ylim = NULL, radius = 0, lapse = 6.5, nolapse = FALSE, @@ -403,31 +403,31 @@ RFTemp <- function(data, lon, lat, oro, lonoro, latoro, method = method) } -#' Nearest neighbour interpolation +#'Nearest neighbour interpolation #' -#' @description The input field is interpolated onto the output -#' coordinate grid using nearest neighbours or bilinear interpolation. -#' The input lon grid must be monotone increasing. -#' The input lat grid can be irregularly spaced (e.g. a Gaussian grid) -#' The output grid can be irregularly spaced in lon and/or lat. -#' @author Jost von Hardenberg, \email{j.vonhardenberg@isac.cnr.it} -#' @param z matrix with the input field to interpolate (assumed to -#' include also a third time dimension) -#' @param lon vector of input longitudes -#' @param lat vector of input latitudes -#' @param lonp vector of output longitudes -#' @param latp vector of output latitudes -#' @param method string indicating the interpolation method -#' ("nearest" or "bilinear" (default)) -#' @return The interpolated field. -#' @examples -#' lon = 5:11 -#' lat = 35:40 -#' z = runif(7 * 6 * 2); dim(z) = c(7, 6, 2) -#' lonp = seq(5, 10, 0.2) -#' latp = seq(35, 40, 0.2) -#' zo <- .interp2d(z, lon, lat, lonp, latp, method = "nearest") -#' @noRd +#'@description The input field is interpolated onto the output +#'coordinate grid using nearest neighbours or bilinear interpolation. +#'The input lon grid must be monotone increasing. +#'The input lat grid can be irregularly spaced (e.g. a Gaussian grid) +#'The output grid can be irregularly spaced in lon and/or lat. +#'@author Jost von Hardenberg, \email{j.vonhardenberg@isac.cnr.it} +#'@param z Matrix with the input field to interpolate (assumed to +#' include also a third time dimension) +#'@param lon Vector of input longitudes. +#'@param lat Vector of input latitudes. +#'@param lonp Vector of output longitudes. +#'@param latp Vector of output latitudes. +#'@param method String indicating the interpolation method ("nearest" or +#' "bilinear" (default)). +#'@return The interpolated field. +#'@examples +#'lon = 5:11 +#'lat = 35:40 +#'z = runif(7 * 6 * 2); dim(z) = c(7, 6, 2) +#'lonp = seq(5, 10, 0.2) +#'latp = seq(35, 40, 0.2) +#'zo <- .interp2d(z, lon, lat, lonp, latp, method = "nearest") +#'@noRd .interp2d <- function(z, lon, lat, lonp, latp, method="bilinear") { nx <- length(lonp) @@ -502,21 +502,21 @@ RFTemp <- function(data, lon, lat, oro, lonoro, latoro, return(zo) } -#' Smoothening using convolution with a circular kernel +#'Smoothening using convolution with a circular kernel #' -#' @description The input field is convolved with a circular kernel with equal -#' weights. Takes into account missing values. -#' @author Jost von Hardenberg, \email{j.vonhardenberg@isac.cnr.it} -#' @param z matrix with the input field to smoothen, with dimensions `c(ns, ns)` -#' @param sdim the smoothing kernel radius in pixel -#' @return The smoothened field. -#' @examples -#' z <- rnorm(64 * 64) -#' dim(z) <- c(64, 64) -#' zs <- smooth(z, 8) -#' sd(zs) -#' # [1] 0.1334648 -#' @noRd +#'@description The input field is convolved with a circular kernel with equal +#'weights. Takes into account missing values. +#'@author Jost von Hardenberg, \email{j.vonhardenberg@isac.cnr.it} +#'@param z Matrix with the input field to smoothen, with dimensions `c(ns, ns)` +#'@param sdim The smoothing kernel radius in pixel. +#'@return The smoothened field. +#'@examples +#'z <- rnorm(64 * 64) +#'dim(z) <- c(64, 64) +#'zs <- smooth(z, 8) +#'sd(zs) +#'# [1] 0.1334648 +#'@noRd .smooth <- function(z, sdim) { nsx <- dim(z)[1] nsy <- dim(z)[2] diff --git a/R/CST_RFWeights.R b/R/CST_RFWeights.R index fa7eec75045717fdd08918dcc1b1d0b19cbd77f6..cd328b1aa8bc9fcdd1665153b165ffe61d8cf8a7 100644 --- a/R/CST_RFWeights.R +++ b/R/CST_RFWeights.R @@ -1,53 +1,61 @@ -#' Compute climatological weights for RainFARM stochastic precipitation downscaling +#'Compute climatological weights for RainFARM stochastic precipitation downscaling #' -#' @author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} +#'@author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} #' -#' @description Compute climatological ("orographic") weights from a fine-scale precipitation climatology file. -#' @references Terzago, S., Palazzi, E., & von Hardenberg, J. (2018). -#' Stochastic downscaling of precipitation in complex orography: -#' A simple method to reproduce a realistic fine-scale climatology. -#' Natural Hazards and Earth System Sciences, 18(11), -#' 2825-2840. http://doi.org/10.5194/nhess-18-2825-2018 . -#' @param climfile Filename of a fine-scale precipitation climatology. -#' The file is expected to be in NetCDF format and should contain -#' at least one precipitation field. If several fields at different times are provided, -#' a climatology is derived by time averaging. -#' Suitable climatology files could be for example a fine-scale precipitation climatology -#' from a high-resolution regional climate model (see e.g. Terzago et al. 2018), a local -#' high-resolution gridded climatology from observations, or a reconstruction such as those which -#' can be downloaded from the WORLDCLIM (http://www.worldclim.org) or CHELSA (http://chelsa-climate.org) -#' websites. The latter data will need to be converted to NetCDF format before being used (see for example the GDAL tools (https://www.gdal.org). -#' It could also be a 's2dv_cube' object. -#' @param nf Refinement factor for downscaling (the output resolution is increased by this factor). -#' @param lon Vector of longitudes. -#' @param lat Vector of latitudes. -#' The number of longitudes and latitudes is expected to be even and the same. If not -#' the function will perform a subsetting to ensure this condition. -#' @param varname Name of the variable to be read from \code{climfile}. -#' @param fsmooth Logical to use smooth conservation (default) or large-scale box-average conservation. -#' @param lonname a character string indicating the name of the longitudinal dimension set as 'lon' by default. -#' @param latname a character string indicating the name of the latitudinal dimension set as 'lat' by default. -#' @param ncores an integer that indicates the number of cores for parallel computations using multiApply function. The default value is one. +#'@description Compute climatological ("orographic") weights from a fine-scale +#'precipitation climatology file. +#'@references Terzago, S., Palazzi, E., & von Hardenberg, J. (2018). +#'Stochastic downscaling of precipitation in complex orography: +#'A simple method to reproduce a realistic fine-scale climatology. +#'Natural Hazards and Earth System Sciences, 18(11), +#'2825-2840. \url{http://doi.org/10.5194/nhess-18-2825-2018} . +#'@param climfile Filename of a fine-scale precipitation climatology. The file +#' is expected to be in NetCDF format and should contain at least one +#' precipitation field. If several fields at different times are provided, +#' a climatology is derived by time averaging. Suitable climatology files could +#' be for example a fine-scale precipitation climatology from a high-resolution +#' regional climate model (see e.g. Terzago et al. 2018), a local +#' high-resolution gridded climatology from observations, or a reconstruction +#' such as those which can be downloaded from the WORLDCLIM +#' (\url{http://www.worldclim.org}) or CHELSA (\url{http://chelsa-climate.org}) +#' websites. The latter data will need to be converted to NetCDF format before +#' being used (see for example the GDAL tools (\url{https://www.gdal.org}). It +#' could also be an 's2dv_cube' object. +#'@param nf Refinement factor for downscaling (the output resolution is +#' increased by this factor). +#'@param lon Vector of longitudes. +#'@param lat Vector of latitudes. The number of longitudes and latitudes is +#' expected to be even and the same. If not the function will perform a +#' subsetting to ensure this condition. +#'@param varname Name of the variable to be read from \code{climfile}. +#'@param fsmooth Logical to use smooth conservation (default) or large-scale +#' box-average conservation. +#'@param lonname A character string indicating the name of the longitudinal +#' dimension set as 'lon' by default. +#'@param latname A character string indicating the name of the latitudinal +#' dimension set as 'lat' by default. +#'@param ncores An integer that indicates the number of cores for parallel +#' computations using multiApply function. The default value is one. #' -#' @return An object of class 's2dv_cube' containing in matrix \code{data} the weights with dimensions (lon, lat). -#' @import ncdf4 -#' @import rainfarmr -#' @import multiApply -#' @importFrom utils tail -#' @importFrom utils head -#' @examples -#' # Create weights to be used with the CST_RainFARM() or RainFARM() functions -#' # using an external fine-scale climatology file. +#'@return An object of class 's2dv_cube' containing in matrix \code{data} the +#'weights with dimensions (lon, lat). +#'@import ncdf4 +#'@import rainfarmr +#'@import multiApply +#'@importFrom utils tail +#'@importFrom utils head +#'@examples +#'# Create weights to be used with the CST_RainFARM() or RainFARM() functions +#'# using an external fine-scale climatology file. #' -#' \dontrun{ -#' # Specify lon and lat of the input -#' lon <- seq(10,13.5,0.5) -#' lat <- seq(40,43.5,0.5) -#' nf <- 8 -#' ww <- CST_RFWeights("./worldclim.nc", nf, lon, lat, fsmooth = TRUE) -#' } -#' @export - +#'\dontrun{ +#'# Specify lon and lat of the input +#'lon <- seq(10,13.5,0.5) +#'lat <- seq(40,43.5,0.5) +#'nf <- 8 +#'ww <- CST_RFWeights("./worldclim.nc", nf, lon, lat, fsmooth = TRUE) +#'} +#'@export CST_RFWeights <- function(climfile, nf, lon, lat, varname = NULL, fsmooth = TRUE, lonname = 'lon', latname = 'lat', ncores = NULL) { @@ -106,40 +114,50 @@ CST_RFWeights <- function(climfile, nf, lon, lat, varname = NULL, } return(climfile) } -#' Compute climatological weights for RainFARM stochastic precipitation downscaling +#'Compute climatological weights for RainFARM stochastic precipitation downscaling #' -#' @author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} +#'@author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} #' -#' @description Compute climatological ("orographic") weights from a fine-scale precipitation climatology file. -#' @references Terzago, S., Palazzi, E., & von Hardenberg, J. (2018). -#' Stochastic downscaling of precipitation in complex orography: -#' A simple method to reproduce a realistic fine-scale climatology. -#' Natural Hazards and Earth System Sciences, 18(11), -#' 2825-2840. http://doi.org/10.5194/nhess-18-2825-2018 . -#' @param zclim a multi-dimensional array with named dimension containing at least one precipiation field with spatial dimensions. -#' @param lonin a vector indicating the longitudinal coordinates corresponding to the \code{zclim} parameter. -#' @param latin a vector indicating the latitudinal coordinates corresponding to the \code{zclim} parameter. -#' @param nf Refinement factor for downscaling (the output resolution is increased by this factor). -#' @param lon Vector of longitudes. -#' @param lat Vector of latitudes. -#' The number of longitudes and latitudes is expected to be even and the same. If not -#' the function will perform a subsetting to ensure this condition. -#' @param fsmooth Logical to use smooth conservation (default) or large-scale box-average conservation. -#' @param lonname a character string indicating the name of the longitudinal dimension set as 'lon' by default. -#' @param latname a character string indicating the name of the latitudinal dimension set as 'lat' by default. -#' @param ncores an integer that indicates the number of cores for parallel computations using multiApply function. The default value is one. +#'@description Compute climatological ("orographic") weights from a fine-scale +#'precipitation climatology file. +#'@references Terzago, S., Palazzi, E., & von Hardenberg, J. (2018). +#'Stochastic downscaling of precipitation in complex orography: +#'A simple method to reproduce a realistic fine-scale climatology. +#'Natural Hazards and Earth System Sciences, 18(11), +#'2825-2840. \url{http://doi.org/10.5194/nhess-18-2825-2018}. +#'@param zclim A multi-dimensional array with named dimension containing at +#' least one precipiation field with spatial dimensions. +#'@param lonin A vector indicating the longitudinal coordinates corresponding to +#' the \code{zclim} parameter. +#'@param latin A vector indicating the latitudinal coordinates corresponding to +#' the \code{zclim} parameter. +#'@param nf Refinement factor for downscaling (the output resolution is +#' increased by this factor). +#'@param lon Vector of longitudes. +#'@param lat Vector of latitudes. The number of longitudes and latitudes is +#' expected to be even and the same. If not the function will perform a +#' subsetting to ensure this condition. +#'@param fsmooth Logical to use smooth conservation (default) or large-scale +#' box-average conservation. +#'@param lonname A character string indicating the name of the longitudinal +#' dimension set as 'lon' by default. +#'@param latname A character string indicating the name of the latitudinal +#' dimension set as 'lat' by default. +#'@param ncores An integer that indicates the number of cores for parallel +#' computations using multiApply function. The default value is one. #' -#' @return An object of class 's2dv_cube' containing in matrix \code{data} the weights with dimensions (lon, lat). -#' @import ncdf4 -#' @import rainfarmr -#' @import multiApply -#' @importFrom utils tail -#' @importFrom utils head -#' @examples -#' a <- array(1:2500, c(lat = 50, lon = 50)) -#' res <- RF_Weights(a, seq(0.1 ,5, 0.1), seq(0.1 ,5, 0.1), -#' nf = 5, lat = 1:5, lon = 1:5) -#' @export +#'@return An object of class 's2dv_cube' containing in matrix \code{data} the +#'weights with dimensions (lon, lat). +#'@import ncdf4 +#'@import rainfarmr +#'@import multiApply +#'@importFrom utils tail +#'@importFrom utils head +#'@examples +#'a <- array(1:2500, c(lat = 50, lon = 50)) +#'res <- RF_Weights(a, seq(0.1 ,5, 0.1), seq(0.1 ,5, 0.1), +#' nf = 5, lat = 1:5, lon = 1:5) +#'@export RF_Weights <- function(zclim, latin, lonin, nf, lat, lon, fsmooth = TRUE, lonname = 'lon', latname = 'lat', ncores = NULL) { x <- Apply(list(zclim), target_dims = c(lonname, latname), fun = rf_weights, diff --git a/R/CST_RainFARM.R b/R/CST_RainFARM.R index 62e9339e913c1fbc3613b8c032efd8265dc43730..7d16cffd7493fd8abf416cb9da0317fda78a0d0d 100644 --- a/R/CST_RainFARM.R +++ b/R/CST_RainFARM.R @@ -1,90 +1,88 @@ -#' @rdname CST_RainFARM -#' @title RainFARM stochastic precipitation downscaling of a CSTools object +#'@rdname CST_RainFARM +#'@title RainFARM stochastic precipitation downscaling of a CSTools object #' -#' @author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} +#'@author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} #' -#' @description This function implements the RainFARM stochastic precipitation -#' downscaling method and accepts a CSTools object (an object of the class -#' 's2dv_cube' as provided by `CST_Load`) as input. -#' Adapted for climate downscaling and including orographic correction -#' as described in Terzago et al. 2018. -#' @references Terzago, S. et al. (2018). NHESS 18(11), 2825-2840. -#' http://doi.org/10.5194/nhess-18-2825-2018 ; -#' D'Onofrio et al. (2014), J of Hydrometeorology 15, 830-843; Rebora et. al. (2006), JHM 7, 724. -#' @param data An object of the class 's2dv_cube' as returned by `CST_Load`, -#' containing the spatial precipitation fields to downscale. -#' The data object is expected to have an element named \code{$data} with at least two -#' spatial dimensions named "lon" and "lat" and one or more dimensions over which -#' to compute average spectral slopes (unless specified with parameter \code{slope}), -#' which can be specified by parameter \code{time_dim}. -#' The number of longitudes and latitudes in the input data is expected to be even and the same. If not -#' the function will perform a subsetting to ensure this condition. -#' @param weights Matrix with climatological weights which can be obtained using -#' the \code{CST_RFWeights} function. If \code{weights=1.} (default) no weights are used. -#' The names of these dimensions must be at least 'lon' and 'lat'. -#' @param nf Refinement factor for downscaling (the output resolution is increased by this factor). -#' @param slope Prescribed spectral slope. The default is \code{slope=0.} -#' meaning that the slope is determined automatically over the dimensions specified by \code{time_dim}. A 1D array with named dimension can be provided (see details and examples) -#' @param kmin First wavenumber for spectral slope (default: \code{kmin=1}). -#' @param nens Number of ensemble members to produce (default: \code{nens=1}). -#' @param fglob Logical to conserve global precipitation over the domain (default: FALSE). -#' @param fsmooth Logical to conserve precipitation with a smoothing kernel (default: TRUE). -#' @param time_dim String or character array with name(s) of dimension(s) -#' (e.g. "ftime", "sdate", "member" ...) over which to compute spectral slopes. -#' If a character array of dimension names is provided, the spectral slopes -#' will be computed as an average over all elements belonging to those dimensions. -#' If omitted one of c("ftime", "sdate", "time") is searched and the first one with more -#' than one element is chosen. -#' @param verbose Logical for verbose output (default: FALSE). -#' @param drop_realization_dim Logical to remove the "realization" stochastic ensemble dimension, -#' needed for saving data through function CST_SaveData (default: FALSE) -#' with the following behaviour if set to TRUE: +#'@description This function implements the RainFARM stochastic precipitation +#'downscaling method and accepts a CSTools object (an object of the class +#''s2dv_cube' as provided by `CST_Load`) as input. +#'Adapted for climate downscaling and including orographic correction +#'as described in Terzago et al. 2018. +#'@references Terzago, S. et al. (2018). NHESS 18(11), 2825-2840. +#'\url{http://doi.org/10.5194/nhess-18-2825-2018} ; +#'D'Onofrio et al. (2014), J of Hydrometeorology 15, 830-843; Rebora et. al. +#'(2006), JHM 7, 724. +#'@param data An object of the class 's2dv_cube' as returned by `CST_Load`, +#' containing the spatial precipitation fields to downscale. +#' The data object is expected to have an element named \code{$data} with at +#' least two spatial dimensions named "lon" and "lat" and one or more +#' dimensions over which to compute average spectral slopes (unless specified +#' with parameter \code{slope}), which can be specified by parameter +#' \code{time_dim}. The number of longitudes and latitudes in the input data is +#' expected to be even and the same. If not the function will perform a +#' subsetting to ensure this condition. +#'@param weights Matrix with climatological weights which can be obtained using +#' the \code{CST_RFWeights} function. If \code{weights=1.} (default) no weights +#' are used. The names of these dimensions must be at least 'lon' and 'lat'. +#'@param nf Refinement factor for downscaling (the output resolution is +#' increased by this factor). +#'@param slope Prescribed spectral slope. The default is \code{slope=0.} +#' meaning that the slope is determined automatically over the dimensions +#' specified by \code{time_dim}. A 1D array with named dimension can be +#' provided (see details and examples). +#'@param kmin First wavenumber for spectral slope (default: \code{kmin=1}). +#'@param nens Number of ensemble members to produce (default: \code{nens=1}). +#'@param fglob Logical to conserve global precipitation over the domain +#' (default: FALSE). +#'@param fsmooth Logical to conserve precipitation with a smoothing kernel +#' (default: TRUE). +#'@param time_dim String or character array with name(s) of dimension(s) +#' (e.g. "ftime", "sdate", "member" ...) over which to compute spectral slopes. +#' If a character array of dimension names is provided, the spectral slopes +#' will be computed as an average over all elements belonging to those +#' dimensions. If omitted one of c("ftime", "sdate", "time") is searched and +#' the first one with more than one element is chosen. +#'@param verbose Logical for verbose output (default: FALSE). +#'@param drop_realization_dim Logical to remove the "realization" stochastic +#' ensemble dimension, needed for saving data through function CST_SaveData +#' (default: FALSE) with the following behaviour if set to TRUE: +#' \enumerate{ +#' \item{if \code{nens==1}: the dimension is dropped;} +#' \item{if \code{nens>1} and a "member" dimension exists: the "realization" +#' and "member" dimensions are compacted (multiplied) and the resulting +#' dimension is named "member";} +#' \item{if \code{nens>1} and a "member" dimension does not exist: the +#' "realization" dimension is renamed to "member".} +#' } +#'@param nprocs The number of parallel processes to spawn for the use for +#' parallel computation in multiple cores. (default: 1) #' -#' 1) if \code{nens==1}: the dimension is dropped; -#' -#' 2) if \code{nens>1} and a "member" dimension exists: -#' the "realization" and "member" dimensions are compacted (multiplied) and the resulting dimension is named "member"; -#' -#' 3) if \code{nens>1} and a "member" dimension does not exist: the "realization" dimension is renamed to "member". -#' @param nprocs The number of parallel processes to spawn for the use for parallel computation in multiple cores. (default: 1) -#' -#' @return CST_RainFARM() returns a downscaled CSTools object (i.e., of the -#' class 's2dv_cube'). -#' If \code{nens>1} an additional dimension named "realizatio"n is added to the -#' \code{$data} array after the "member" dimension (unless -#' \code{drop_realization_dim=TRUE} is specified). -#' The ordering of the remaining dimensions in the \code{$data} element of the input object is maintained. -#' @details Wether parameter 'slope' and 'weights' presents seasonality dependency, a dimension name should match between these parameters and the input data in parameter 'data'. See example 2 below where weights and slope vary with 'sdate' dimension. -#' @import multiApply -#' @import rainfarmr -#' @examples -#' #Example 1: using CST_RainFARM for a CSTools object -#' nf <- 8 # Choose a downscaling by factor 8 -#' exp <- 1 : (2 * 3 * 4 * 8 * 8) -#' dim(exp) <- c(dataset = 1, member = 2, sdate = 3, ftime = 4, lat = 8, lon = 8) -#' lon <- seq(10, 13.5, 0.5) -#' dim(lon) <- c(lon = length(lon)) -#' lat <- seq(40, 43.5, 0.5) -#' dim(lat) <- c(lat = length(lat)) -#' data <- list(data = exp, lon = lon, lat = lat) -#' # Create a test array of weights -#' ww <- array(1., dim = c(lon = 8 * nf, lat = 8 * nf)) -#' res <- CST_RainFARM(data, nf = nf, weights = ww, nens=3) -#' str(res) -#' #List of 3 -#' # $ data: num [1, 1:2, 1:3, 1:3, 1:4, 1:64, 1:64] 260 553 281 278 143 ... -#' # $ lon : num [1:64] 9.78 9.84 9.91 9.97 10.03 ... -#' # $ lat : num [1:64] 39.8 39.8 39.9 40 40 ... -#' dim(res$data) -#' # dataset member realization sdate ftime lat lon -#' # 1 2 3 3 4 64 64 -#' -#' # Example 2: -#' slo <- array(c(0.1, 0.5, 0.7), c(sdate= 3)) -#' wei <- array(rnorm(8 * 8 * 3), c(lon = 8, lat = 8, sdate = 3)) -#' res <- CST_RainFARM(lonlat_prec, -#' weights = wei, slope = slo, nf = 2) -#' @export +#'@return CST_RainFARM() returns a downscaled CSTools object (i.e., of the +#'class 's2dv_cube'). If \code{nens>1} an additional dimension named +#'"realization" is added to the \code{$data} array after the "member" dimension +#'(unless \code{drop_realization_dim=TRUE} is specified). The ordering of the +#'remaining dimensions in the \code{$data} element of the input object is +#'maintained. +#'@details Wether parameter 'slope' and 'weights' presents seasonality +#'dependency, a dimension name should match between these parameters and the +#'input data in parameter 'data'. See example 2 below where weights and slope +#'vary with 'sdate' dimension. +#'@import multiApply +#'@import rainfarmr +#'@examples +#'# Example 1: using CST_RainFARM for a CSTools object +#'nf <- 8 # Choose a downscaling by factor 8 +#'exp <- 1 : (2 * 3 * 4 * 8 * 8) +#'dim(exp) <- c(dataset = 1, member = 2, sdate = 3, ftime = 4, lat = 8, lon = 8) +#'lon <- seq(10, 13.5, 0.5) +#'dim(lon) <- c(lon = length(lon)) +#'lat <- seq(40, 43.5, 0.5) +#'dim(lat) <- c(lat = length(lat)) +#'data <- list(data = exp, lon = lon, lat = lat) +#'# Create a test array of weights +#'ww <- array(1., dim = c(lon = 8 * nf, lat = 8 * nf)) +#'res <- CST_RainFARM(data, nf = nf, weights = ww, nens = 3) +#'@export CST_RainFARM <- function(data, weights = 1., slope = 0, nf, kmin = 1, nens = 1, fglob = FALSE, fsmooth = TRUE, nprocs = 1, time_dim = NULL, verbose = FALSE, @@ -105,101 +103,95 @@ CST_RainFARM <- function(data, weights = 1., slope = 0, nf, kmin = 1, return(data) } -#' @rdname RainFARM -#' @title RainFARM stochastic precipitation downscaling (reduced version) -#' @author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} -#' @description This function implements the RainFARM stochastic precipitation downscaling method -#' and accepts in input an array with named dims ("lon", "lat") -#' and one or more dimension (such as "ftime", "sdate" or "time") -#' over which to average automatically determined spectral slopes. -#' Adapted for climate downscaling and including orographic correction. -#' References: -#' Terzago, S. et al. (2018). NHESS 18(11), 2825-2840. http://doi.org/10.5194/nhess-18-2825-2018, -#' D'Onofrio et al. (2014), J of Hydrometeorology 15, 830-843; Rebora et. al. (2006), JHM 7, 724. -#' @param data Precipitation array to downscale. -#' The input array is expected to have at least two dimensions named "lon" and "lat" by default -#' (these default names can be changed with the \code{lon_dim} and \code{lat_dim} parameters) -#' and one or more dimensions over which to average these slopes, -#' which can be specified by parameter \code{time_dim}. -#' The number of longitudes and latitudes in the input data is expected to be even and the same. If not -#' the function will perform a subsetting to ensure this condition. -#' @param lon Vector or array of longitudes. -#' @param lat Vector or array of latitudes. -#' @param weights multi-dimensional array with climatological weights which can be obtained using -#' the \code{CST_RFWeights} function. If \code{weights=1.} (default) no weights are used. -#' The names of these dimensions must be at least 'lon' and 'lat'. -#' @param nf Refinement factor for downscaling (the output resolution is increased by this factor). -#' @param slope Prescribed spectral slope. The default is \code{slope=0.} -#' meaning that the slope is determined automatically over the dimensions specified by \code{time_dim}. A 1D array with named dimension can be provided (see details and examples) -#' @param kmin First wavenumber for spectral slope (default: \code{kmin=1}). -#' @param nens Number of ensemble members to produce (default: \code{nens=1}). -#' @param fglob Logical to conseve global precipitation over the domain (default: FALSE) -#' @param fsmooth Logical to conserve precipitation with a smoothing kernel (default: TRUE) -#' @param time_dim String or character array with name(s) of time dimension(s) -#' (e.g. "ftime", "sdate", "time" ...) over which to compute spectral slopes. -#' If a character array of dimension names is provided, the spectral slopes -#' will be computed over all elements belonging to those dimensions. -#' If omitted one of c("ftime", "sdate", "time") -#' is searched and the first one with more than one element is chosen. -#' @param lon_dim Name of lon dimension ("lon" by default). -#' @param lat_dim Name of lat dimension ("lat" by default). -#' @param verbose logical for verbose output (default: FALSE). -#' @param drop_realization_dim Logical to remove the "realization" stochastic ensemble dimension (default: FALSE) -#' with the following behaviour if set to TRUE: -#' -#' 1) if \code{nens==1}: the dimension is dropped; -#' -#' 2) if \code{nens>1} and a "member" dimension exists: -#' the "realization" and "member" dimensions are compacted (multiplied) and the resulting dimension is named "member"; -#' -#' 3) if \code{nens>1} and a "member" dimension does not exist: the "realization" dimension is renamed to "member". -#' -#' @param nprocs The number of parallel processes to spawn for the use for parallel computation in multiple cores. (default: 1) -#' @return RainFARM() returns a list containing the fine-scale longitudes, latitudes -#' and the sequence of \code{nens} downscaled fields. -#' If \code{nens>1} an additional dimension named "realization" is added to the output array -#' after the "member" dimension (if it exists and unless \code{drop_realization_dim=TRUE} is specified). -#' The ordering of the remaining dimensions in the \code{exp} element of the input object is maintained. -#' @details Wether parameter 'slope' and 'weights' presents seasonality dependency, a dimension name should match between these parameters and the input data in parameter 'data'. See example 2 below where weights and slope vary with 'sdate' dimension. -#' @import multiApply -#' @importFrom ClimProjDiags Subset -#' @importFrom abind abind -#' @export -#' @examples -#' # Example for the 'reduced' RainFARM function -#' nf <- 8 # Choose a downscaling by factor 8 -#' nens <- 3 # Number of ensemble members -#' # create a test array with dimension 8x8 and 20 timesteps -#' # or provide your own read from a netcdf file -#' pr <- rnorm(8 * 8 * 20) -#' dim(pr) <- c(lon = 8, lat = 8, ftime = 20) -#' lon_mat <- seq(10, 13.5, 0.5) # could also be a 2d matrix -#' lat_mat <- seq(40, 43.5, 0.5) -#' # Create a test array of weights -#' ww <- array(1., dim = c(lon = 8 * nf, lat = 8 * nf)) -#' # or create proper weights using an external fine-scale climatology file -#' # Specify a weightsfn filename if you wish to save the weights -#' \dontrun{ -#' ww <- CST_RFWeights("./worldclim.nc", nf, lon = lon_mat, lat = lat_mat, -#' fsmooth = TRUE) -#' } -#' # downscale using weights (ww=1. means do not use weights) -#' res <- RainFARM(pr, lon_mat, lat_mat, nf, -#' fsmooth = TRUE, fglob = FALSE, -#' weights = ww, nens = 2, verbose = TRUE) -#' str(res) -#' #List of 3 -#' # $ data: num [1:3, 1:20, 1:64, 1:64] 0.186 0.212 0.138 3.748 0.679 ... -#' # $ lon : num [1:64] 9.78 9.84 9.91 9.97 10.03 ... -#' # $ lat : num [1:64] 39.8 39.8 39.9 40 40 ... -#' dim(res$data) -#' # lon lat ftime realization -#' # 64 64 20 2 -#' # Example 2: -#' slo <- array(c(0.1, 0.5, 0.7), c(sdate= 3)) -#' wei <- array(rnorm(8*8*3), c(lon = 8, lat = 8, sdate = 3)) -#' res <- RainFARM(lonlat_prec$data, lon = lonlat_prec$lon, -#' lat = lonlat_prec$lat, weights = wei, slope = slo, nf = 2) +#'@rdname RainFARM +#'@title RainFARM stochastic precipitation downscaling (reduced version) +#'@author Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} +#'@description This function implements the RainFARM stochastic precipitation downscaling method +#'and accepts in input an array with named dims ("lon", "lat") +#'and one or more dimension (such as "ftime", "sdate" or "time") +#'over which to average automatically determined spectral slopes. +#'Adapted for climate downscaling and including orographic correction. +#'References: +#'Terzago, S. et al. (2018). NHESS 18(11), 2825-2840. http://doi.org/10.5194/nhess-18-2825-2018, +#'D'Onofrio et al. (2014), J of Hydrometeorology 15, 830-843; Rebora et. al. (2006), JHM 7, 724. +#'@param data Precipitation array to downscale. The input array is expected to +#' have at least two dimensions named "lon" and "lat" by default (these default +#' names can be changed with the \code{lon_dim} and \code{lat_dim} parameters) +#' and one or more dimensions over which to average these slopes, which can be +#' specified by parameter \code{time_dim}. The number of longitudes and +#' latitudes in the input data is expected to be even and the same. If not +#' the function will perform a subsetting to ensure this condition. +#'@param lon Vector or array of longitudes. +#'@param lat Vector or array of latitudes. +#'@param weights Multi-dimensional array with climatological weights which can +#' be obtained using the \code{CST_RFWeights} function. If \code{weights=1.} +#' (default) no weights are used. The names of these dimensions must be at +#' least 'lon' and 'lat'. +#'@param nf Refinement factor for downscaling (the output resolution is +#' increased by this factor). +#'@param slope Prescribed spectral slope. The default is \code{slope=0.} +#' meaning that the slope is determined automatically over the dimensions +#' specified by \code{time_dim}. A 1D array with named dimension can be +#' provided (see details and examples). +#'@param kmin First wavenumber for spectral slope (default: \code{kmin=1}). +#'@param nens Number of ensemble members to produce (default: \code{nens=1}). +#'@param fglob Logical to conseve global precipitation over the domain +#' (default: FALSE). +#'@param fsmooth Logical to conserve precipitation with a smoothing kernel +#' (default: TRUE). +#'@param time_dim String or character array with name(s) of time dimension(s) +#' (e.g. "ftime", "sdate", "time" ...) over which to compute spectral slopes. +#' If a character array of dimension names is provided, the spectral slopes +#' will be computed over all elements belonging to those dimensions. +#' If omitted one of c("ftime", "sdate", "time") is searched and the first one +#' with more than one element is chosen. +#'@param lon_dim Name of lon dimension ("lon" by default). +#'@param lat_dim Name of lat dimension ("lat" by default). +#'@param verbose logical for verbose output (default: FALSE). +#'@param drop_realization_dim Logical to remove the "realization" stochastic +#' ensemble dimension (default: FALSE) with the following behaviour if set to +#' TRUE: +#' \enumerate{ +#' \item{if \code{nens==1}: the dimension is dropped;} +#' \item{if \code{nens>1} and a "member" dimension exists: the "realization" +#' and "member" dimensions are compacted (multiplied) and the resulting +#' dimension is named "member";} +#' \item{if \code{nens>1} and a "member" dimension does not exist: the +#' "realization" dimension is renamed to "member".} +#' } +#'@param nprocs The number of parallel processes to spawn for the use for +#' parallel computation in multiple cores. (default: 1) +#'@return RainFARM() Returns a list containing the fine-scale longitudes, +#' latitudes and the sequence of \code{nens} downscaled fields. If +#' \code{nens>1} an additional dimension named "realization" is added to the +#' output array after the "member" dimension (if it exists and unless +#' \code{drop_realization_dim=TRUE} is specified). The ordering of the +#' remaining dimensions in the \code{exp} element of the input object is +#' maintained. +#'@details Wether parameter 'slope' and 'weights' presents seasonality +#'dependency, a dimension name should match between these parameters and the +#'input data in parameter 'data'. See example 2 below where weights and slope +#'vary with 'sdate' dimension. +#'@import multiApply +#'@importFrom ClimProjDiags Subset +#'@importFrom abind abind +#'@examples +#'# Example for the 'reduced' RainFARM function +#'nf <- 8 # Choose a downscaling by factor 8 +#'nens <- 3 # Number of ensemble members +#'# create a test array with dimension 8x8 and 20 timesteps +#'# or provide your own read from a netcdf file +#'pr <- rnorm(8 * 8 * 20) +#'dim(pr) <- c(lon = 8, lat = 8, ftime = 20) +#'lon_mat <- seq(10, 13.5, 0.5) # could also be a 2d matrix +#'lat_mat <- seq(40, 43.5, 0.5) +#'# Create a test array of weights +#'ww <- array(1., dim = c(lon = 8 * nf, lat = 8 * nf)) +#'# downscale using weights (ww=1. means do not use weights) +#'res <- RainFARM(pr, lon_mat, lat_mat, nf, +#' fsmooth = TRUE, fglob = FALSE, +#' weights = ww, nens = 2, verbose = TRUE) +#'@export RainFARM <- function(data, lon, lat, nf, weights = 1., nens = 1, slope = 0, kmin = 1, fglob = FALSE, fsmooth = TRUE, nprocs = 1, time_dim = NULL, lon_dim = "lon", lat_dim = "lat", @@ -345,20 +337,25 @@ RainFARM <- function(data, lon, lat, nf, weights = 1., nens = 1, return(list(data = result, lon = lon_f, lat = lat_f)) } -#' Atomic RainFARM -#' @param pr Precipitation array to downscale with dimensions (lon, lat, time). -#' @param weights Matrix with climatological weights which can be obtained using -#' the \code{CST_RFWeights} function (default: \code{weights=1.} i.e. no weights). -#' @param slope Prescribed spectral slope (default: \code{slope=0.} -#' @param nf Refinement factor for downscaling (the output resolution is increased by this factor). -#' meaning that the slope is determined automatically over the dimensions specified by \code{time_dim}. -#' @param kmin First wavenumber for spectral slope (default: \code{kmin=1}). -#' @param nens Number of ensemble members to produce (default: \code{nens=1}). -#' @param fglob Logical to conseve global precipitation over the domain (default: FALSE). -#' @param fsmooth Logical to conserve precipitation with a smoothing kernel (default: TRUE). -#' @param verbose Logical for verbose output (default: FALSE). -#' @return .RainFARM returns a downscaled array with dimensions (lon, lat, time, realization) -#' @noRd +#'Atomic RainFARM +#'@param pr Precipitation array to downscale with dimensions (lon, lat, time). +#'@param weights Matrix with climatological weights which can be obtained using +#' the \code{CST_RFWeights} function (default: \code{weights=1.} i.e. no +#' weights). +#'@param slope Prescribed spectral slope (default: \code{slope=0.} +#'@param nf Refinement factor for downscaling (the output resolution is +#' increased by this factor). Meaning that the slope is determined +#' automatically over the dimensions specified by \code{time_dim}. +#'@param kmin First wavenumber for spectral slope (default: \code{kmin=1}). +#'@param nens Number of ensemble members to produce (default: \code{nens=1}). +#'@param fglob Logical to conseve global precipitation over the domain +#' (default: FALSE). +#'@param fsmooth Logical to conserve precipitation with a smoothing kernel +#' (default: TRUE). +#'@param verbose Logical for verbose output (default: FALSE). +#'@return .RainFARM returns a downscaled array with dimensions (lon, lat, time, +#' realization) +#'@noRd .RainFARM <- function(pr, weights, slope, nf, nens, kmin, fglob, fsmooth, verbose) { posna <- NULL diff --git a/R/CST_RegimesAssign.R b/R/CST_RegimesAssign.R index 99e1380482e886154377845eefb66156933381e6..f3ae5ecd21b88114c80d5017b688ee85726a7db2 100644 --- a/R/CST_RegimesAssign.R +++ b/R/CST_RegimesAssign.R @@ -1,43 +1,54 @@ -#' @rdname CST_RegimesAssign -#' @title Function for matching a field of anomalies with -#' a set of maps used as a reference (e.g. clusters obtained from the WeatherRegime function) +#'@rdname CST_RegimesAssign +#'@title Function for matching a field of anomalies with +#'a set of maps used as a reference (e.g. clusters obtained from the WeatherRegime function) #' -#' @author Verónica Torralba - BSC, \email{veronica.torralba@bsc.es} +#'@author Verónica Torralba - BSC, \email{veronica.torralba@bsc.es} #' -#' @description This function performs the matching between a field of anomalies and a set -#' of maps which will be used as a reference. The anomalies will be assigned to the reference map -#' for which the minimum Eucledian distance (method=’distance’) or highest spatial correlation -#' (method = 'ACC') is obtained. -#' -#'@references Torralba, V. (2019) Seasonal climate prediction for the wind energy sector: methods and tools -#' for the development of a climate service. Thesis. Available online: \url{https://eprints.ucm.es/56841/} +#'@description This function performs the matching between a field of anomalies +#'and a set of maps which will be used as a reference. The anomalies will be +#'assigned to the reference map for which the minimum Eucledian distance +#'(method=’distance’) or highest spatial correlation (method = 'ACC') is +#'obtained. #' -#'@param data a 's2dv_cube' object. - -#'@param ref_maps a 's2dv_cube' object as the output of CST_WeatherRegimes. -#'@param method whether the matching will be performed in terms of minimum distance (default = 'distance') or -#' the maximum spatial correlation (method = 'ACC') between the maps. -#'@param composite a logical parameter indicating if the composite maps are computed or not (default = FALSE). -#'@param memb a logical value indicating whether to compute composites for separate members (default FALSE) or as unique ensemble (TRUE). -#'This option is only available for when parameter 'composite' is set to TRUE and the data object has a dimension named 'member'. -#'@param ncores the number of multicore threads to use for parallel computation. -#'@return A list with two elements \code{$data} (a 's2dv_cube' object containing the composites cluster=1,..,K for case (*1) -# or only k=1 for any specific cluster, i.e., case (*2)) (only when composite = 'TRUE') and \code{$statistics} that includes -#' \code{$pvalue} (array with the same structure as \code{$data} containing the pvalue of the composites obtained through a t-test -#' that accounts for the serial dependence of the data with the same structure as Composite.)(only when composite = 'TRUE'), -#' \code{$cluster} (array with the same dimensions as data (except latitude and longitude which are removed) indicating the ref_maps to which each point is allocated.) , -#' \code{$frequency} (A vector of integers (from k=1,...k n reference maps) indicating the percentage of assignations corresponding to each map.), +#'@references Torralba, V. (2019) Seasonal climate prediction for the wind +#'energy sector: methods and tools for the development of a climate service. +#'Thesis. Available online: \url{https://eprints.ucm.es/56841/} +#' +#'@param data An 's2dv_cube' object. +#'@param ref_maps An 's2dv_cube' object as the output of CST_WeatherRegimes. +#'@param method Whether the matching will be performed in terms of minimum +#' distance (default = 'distance') or the maximum spatial correlation +#' (method = 'ACC') between the maps. +#'@param composite A logical parameter indicating if the composite maps are +#' computed or not (default = FALSE). +#'@param memb A logical value indicating whether to compute composites for +#' separate members (default FALSE) or as unique ensemble (TRUE). This option +#' is only available for when parameter 'composite' is set to TRUE and the data +#' object has a dimension named 'member'. +#'@param ncores The number of multicore threads to use for parallel computation. +#'@return A list with two elements \code{$data} (a 's2dv_cube' object containing +#'the composites cluster=1,..,K for case (*1) or only k=1 for any specific +#'cluster, i.e., case (*2)) (only when composite = 'TRUE') and \code{$statistics} +#'that includes \code{$pvalue} (array with the same structure as \code{$data} +#'containing the pvalue of the composites obtained through a t-test that +#'accounts for the serial dependence of the data with the same structure as +#'Composite.)(only when composite = 'TRUE'), \code{$cluster} (array with the +#'same dimensions as data (except latitude and longitude which are removed) +#'indicating the ref_maps to which each point is allocated.), \code{$frequency} +#'(A vector of integers (from k=1,...k n reference maps) indicating the +#'percentage of assignations corresponding to each map.). #'@importFrom s2dv ACC MeanDims InsertDim #'@import multiApply #'@examples #'\dontrun{ -#'regimes <- CST_WeatherRegimes(data = lonlat_temp$obs, EOFs = FALSE, ncenters = 4) -#'res1 <- CST_RegimesAssign(data = lonlat_temp$exp, ref_maps = regimes, composite = FALSE) -#'res2 <- CST_RegimesAssign(data = lonlat_temp$exp, ref_maps = regimes, composite = TRUE) +#'regimes <- CST_WeatherRegimes(data = lonlat_temp$obs, EOFs = FALSE, +#' ncenters = 4) +#'res1 <- CST_RegimesAssign(data = lonlat_temp$exp, ref_maps = regimes, +#' composite = FALSE) +#'res2 <- CST_RegimesAssign(data = lonlat_temp$exp, ref_maps = regimes, +#' composite = TRUE) #'} #'@export -#' - CST_RegimesAssign <- function(data, ref_maps, method = "distance", composite = FALSE, @@ -73,35 +84,50 @@ CST_RegimesAssign <- function(data, ref_maps, return(data) } -#' @rdname RegimesAssign -#' @title Function for matching a field of anomalies with -#' a set of maps used as a reference (e.g. clusters obtained from the WeatherRegime function). +#'@rdname RegimesAssign +#'@title Function for matching a field of anomalies with +#'a set of maps used as a reference (e.g. clusters obtained from the WeatherRegime function). #' -#' @author Verónica Torralba - BSC, \email{veronica.torralba@bsc.es} +#'@author Verónica Torralba - BSC, \email{veronica.torralba@bsc.es} #' -#' @description This function performs the matching between a field of anomalies and a set -#' of maps which will be used as a reference. The anomalies will be assigned to the reference map -#' for which the minimum Eucledian distance (method = 'distance') or highest spatial correlation -#' (method = 'ACC') is obtained. +#'@description This function performs the matching between a field of anomalies +#'and a set of maps which will be used as a reference. The anomalies will be +#'assigned to the reference map for which the minimum Eucledian distance +#'(method = 'distance') or highest spatial correlation (method = 'ACC') is +#'obtained. #' -#'@references Torralba, V. (2019) Seasonal climate prediction for the wind energy sector: methods and tools for the development of a climate service. Thesis. Available online: \url{https://eprints.ucm.es/56841/} +#'@references Torralba, V. (2019) Seasonal climate prediction for the wind +#'energy sector: methods and tools for the development of a climate service. +#'Thesis. Available online: \url{https://eprints.ucm.es/56841/} #' -#'@param data an array containing anomalies with named dimensions: dataset, member, sdate, ftime, lat and lon. -#'@param ref_maps array with 3-dimensions ('lon', 'lat', 'cluster') containing the maps/clusters that will be used as a reference for the matching. -#'@param method whether the matching will be performed in terms of minimum distance (default = 'distance') or -#' the maximum spatial correlation (method = 'ACC') between the maps. -#'@param lat a vector of latitudes corresponding to the positions provided in data and ref_maps. -#'@param composite a logical parameter indicating if the composite maps are computed or not (default = FALSE). -#'@param memb a logical value indicating whether to compute composites for separate members (default FALSE) or as unique ensemble (TRUE). -#'This option is only available for when parameter 'composite' is set to TRUE and the data object has a dimension named 'member'. -#'@param ncores the number of multicore threads to use for parallel computation. -#'@return A list with elements \code{$composite} (3-d array (lon, lat, k) containing the composites k=1,..,K for case (*1) -# or only k=1 for any specific cluster, i.e., case (*2)) (only if composite='TRUE'), -#' \code{$pvalue} ( array with the same structure as \code{$composite} containing the pvalue of the composites obtained through a t-test -#' that accounts for the serial dependence of the data with the same structure as Composite.) (only if composite='TRUE'), -#' \code{$cluster} (array with the same dimensions as data (except latitude and longitude which are removed) indicating the ref_maps to which each point is allocated.) , -#' \code{$frequency} (A vector of integers (from k = 1, ... k n reference maps) indicating the percentage of assignations corresponding to each map.), -#' +#'@param data An array containing anomalies with named dimensions: dataset, +#' member, sdate, ftime, lat and lon. +#'@param ref_maps Array with 3-dimensions ('lon', 'lat', 'cluster') containing +#' the maps/clusters that will be used as a reference for the matching. +#'@param method Whether the matching will be performed in terms of minimum +#' distance (default = 'distance') or the maximum spatial correlation +#' (method = 'ACC') between the maps. +#'@param lat A vector of latitudes corresponding to the positions provided in +#' data and ref_maps. +#'@param composite A logical parameter indicating if the composite maps are +#' computed or not (default = FALSE). +#'@param memb A logical value indicating whether to compute composites for +#' separate members (default FALSE) or as unique ensemble (TRUE). This option +#' is only available for when parameter 'composite' is set to TRUE and the data +#' object has a dimension named 'member'. +#'@param ncores The number of multicore threads to use for parallel computation. +#'@return A list with elements \code{$composite} (3-d array (lon, lat, k) +#'containing the composites k = 1,..,K for case (*1) or only k = 1 for any specific +#'cluster, i.e., case (*2)) (only if composite = 'TRUE'), \code{$pvalue} (array +#'with the same structure as \code{$composite} containing the pvalue of the +#'composites obtained through a t-test that accounts for the serial dependence +#'of the data with the same structure as Composite.) (only if composite='TRUE'), +#'\code{$cluster} (array with the same dimensions as data (except latitude and +#'longitude which are removed) indicating the ref_maps to which each point is +#'allocated.), \code{$frequency} (A vector of integers (from k = 1, ... k n +#'reference maps) indicating the percentage of assignations corresponding to +#'each map.), +#' #'@importFrom s2dv ACC MeanDims Eno InsertDim #'@import multiApply #'@examples @@ -112,7 +138,6 @@ CST_RegimesAssign <- function(data, ref_maps, #' lat = lonlat_temp$exp$lat, composite = FALSE) #'} #'@export - RegimesAssign <- function(data, ref_maps, lat, method = "distance", composite = FALSE, memb = FALSE, ncores = NULL) { diff --git a/R/CST_SaveExp.R b/R/CST_SaveExp.R index a15cfaa4842e3e26295fe7b4ad003c520f61d7d4..64b06fa50be6a8ff84ad8b50c7fb557b8b491b6c 100644 --- a/R/CST_SaveExp.R +++ b/R/CST_SaveExp.R @@ -7,13 +7,16 @@ #''s2dv_cube' into a NetCDF file, allowing to reload the saved data using #'\code{CST_Load} function. #' -#'@param data an object of class \code{s2dv_cube}. -#'@param destination a character string containing the directory name in which -#'to save the data. NetCDF file for each starting date are saved into the -#'folder tree: destination/experiment/variable/. By default the function -#'creates and saves the data into the folder "CST_Data" in the working -#'directory. -#'@param extra_string a character string to be include as part of the file name, for instance, to identify member or realization. It would be added to the file name between underscore characters. +#'@param data An object of class \code{s2dv_cube}. +#'@param destination A character string containing the directory name in which +#' to save the data. NetCDF file for each starting date are saved into the +#' folder tree: \cr +#' destination/experiment/variable/. By default the function +#' creates and saves the data into the folder "CST_Data" in the working +#' directory. +#'@param extra_string A character string to be include as part of the file name, +#' for instance, to identify member or realization. It would be added to the +#' file name between underscore characters. #' #'@seealso \code{\link{CST_Load}}, \code{\link{as.s2dv_cube}} and \code{\link{s2dv_cube}} #' @@ -60,25 +63,38 @@ CST_SaveExp <- function(data, destination = "./CST_Data", extra_string = NULL) { extra_string = extra_string) } #'Save an experiment in a format compatible with CST_Load -#'@description This function is created for compatibility with CST_Load/Load for saving post-processed datasets such as those calibrated of downscaled with CSTools functions +#'@description This function is created for compatibility with CST_Load/Load for +#'saving post-processed datasets such as those calibrated of downscaled with +#'CSTools functions #' #'@author Perez-Zanon Nuria, \email{nuria.perez@bsc.es} #' -#'@param data an multi-dimensional array with named dimensions (longitude, latitude, time, member, sdate) -#'@param lon vector of logitud corresponding to the longitudinal dimension in data -#'@param lat vector of latitud corresponding to the latitudinal dimension in data -#'@param Dataset a vector of character string indicating the names of the datasets -#'@param var_name a character string indicating the name of the variable to be saved -#'@param units a character string indicating the units of the variable -#'@param startdates a vector of dates indicating the initialization date of each simulations -#'@param Dates a matrix of dates with two dimension 'time' and 'sdate'. -#'@param cdo_grid_name a character string indicating the name of the grid e.g.: 'r360x181' -#'@param projection a character string indicating the projection name -#'@param destination a character string indicating the path where to store the NetCDF files -#'@param extra_string a character string to be include as part of the file name, for instance, to identify member or realization. +#'@param data An multi-dimensional array with named dimensions (longitude, +#' latitude, time, member, sdate). +#'@param lon Vector of logitud corresponding to the longitudinal dimension in +#' data. +#'@param lat Vector of latitud corresponding to the latitudinal dimension in +#' data. +#'@param Dataset A vector of character string indicating the names of the +#' datasets. +#'@param var_name A character string indicating the name of the variable to be +#' saved. +#'@param units A character string indicating the units of the variable. +#'@param startdates A vector of dates indicating the initialization date of each +#' simulations. +#'@param Dates A matrix of dates with two dimension 'time' and 'sdate'. +#'@param cdo_grid_name A character string indicating the name of the grid e.g.: +#' 'r360x181' +#'@param projection A character string indicating the projection name. +#'@param destination A character string indicating the path where to store the +#' NetCDF files. +#'@param extra_string A character string to be include as part of the file name, +#' for instance, to identify member or realization. #' -#'@return the function creates as many files as sdates per dataset. Each file could contain multiple members. It would be added to the file name between underscore characters. -#' The path will be created with the name of the variable and each Datasets. +#'@return The function creates as many files as sdates per dataset. Each file +#'could contain multiple members. It would be added to the file name between +#'underscore characters. The path will be created with the name of the variable +#'and each Datasets. #' #'@import ncdf4 #'@importFrom s2dv Reorder InsertDim diff --git a/R/CST_SplitDim.R b/R/CST_SplitDim.R index a2d93f7d576f4a11a369fb390a80a1edf653d889..03d580cb76888328a2200ed221321f71f5a8c3c6 100644 --- a/R/CST_SplitDim.R +++ b/R/CST_SplitDim.R @@ -2,16 +2,35 @@ #' #'@author Nuria Perez-Zanon, \email{nuria.perez@bsc.es} #' -#'@description This function split a dimension in two. The user can select the dimension to split and provide indices indicating how to split that dimension or dates and the frequency expected (monthly or by day, month and year). The user can also provide a numeric frequency indicating the length of each division. +#'@description This function split a dimension in two. The user can select the +#'dimension to split and provide indices indicating how to split that dimension +#'or dates and the frequency expected (monthly or by day, month and year). The +#'user can also provide a numeric frequency indicating the length of each division. #' -#'@param data a 's2dv_cube' object -#'@param split_dim a character string indicating the name of the dimension to split -#'@param indices a vector of numeric indices or dates. If left at NULL, the dates provided in the s2dv_cube object (element Dates) will be used. -#'@param freq a character string indicating the frequency: by 'day', 'month' and 'year' or 'monthly' (by default). 'month' identifies months between 1 and 12 independently of the year they belong to, while 'monthly' differenciates months from different years. -#'@param new_dim_name a character string indicating the name of the new dimension. -#'@param insert_ftime an integer indicating the number of time steps to add at the begining of the time series. +#'@param data A 's2dv_cube' object +#'@param split_dim A character string indicating the name of the dimension to +#' split. +#'@param indices A vector of numeric indices or dates. If left at NULL, the +#' dates provided in the s2dv_cube object (element Dates) will be used. +#'@param freq A character string indicating the frequency: by 'day', 'month' and +#' 'year' or 'monthly' (by default). 'month' identifies months between 1 and 12 +#' independently of the year they belong to, while 'monthly' differenciates +#' months from different years. +#'@param new_dim_name A character string indicating the name of the new dimension. +#'@param insert_ftime An integer indicating the number of time steps to add at +#' the begining of the time series. #' -#'@details Parameter 'insert_ftime' has been included for the case of using daily data, requiring split the temporal dimensions by months (or similar) and the first lead time doesn't correspondt to the 1st day of the month. In this case, the insert_ftime could be used, to get a final output correctly organized. E.g.: leadtime 1 is the 2nd of November and the input time series extend to the 31st of December. When requiring split by month with \code{inset_ftime = 1}, the 'monthly' dimension of length two will indicate the month (position 1 for November and position 2 for December), dimension 'time' will be length 31. For November, the position 1 and 31 will be NAs, while from positon 2 to 30 will be filled with the data provided. This allows to select correctly days trhough time dimension. +#'@details Parameter 'insert_ftime' has been included for the case of using +#'daily data, requiring split the temporal dimensions by months (or similar) and +#'the first lead time doesn't correspondt to the 1st day of the month. In this +#'case, the insert_ftime could be used, to get a final output correctly +#'organized. E.g.: leadtime 1 is the 2nd of November and the input time series +#'extend to the 31st of December. When requiring split by month with +#'\code{inset_ftime = 1}, the 'monthly' dimension of length two will indicate +#'the month (position 1 for November and position 2 for December), dimension +#''time' will be length 31. For November, the position 1 and 31 will be NAs, +#'while from positon 2 to 30 will be filled with the data provided. This allows +#'to select correctly days trhough time dimension. #'@import abind #'@importFrom ClimProjDiags Subset #'@examples @@ -38,79 +57,86 @@ #'@export CST_SplitDim <- function(data, split_dim = 'time', indices = NULL, freq = 'monthly', new_dim_name = NULL, insert_ftime = NULL) { - if (!inherits(data, 's2dv_cube')) { - stop("Parameter 'data' must be of the class 's2dv_cube', ", - "as output by CSTools::CST_Load.") + if (!inherits(data, 's2dv_cube')) { + stop("Parameter 'data' must be of the class 's2dv_cube', ", + "as output by CSTools::CST_Load.") + } + if (!is.null(insert_ftime)) { + if (!is.numeric(insert_ftime)) { + stop("Parameter 'insert_ftime' should be an integer.") + } else { + if (length(insert_ftime) > 1) { + warning("Parameter 'insert_ftime' must be of length 1, and only the", + " first element will be used.") + insert_ftime <- insert_ftime[1] + } + # adding NAs at the begining of the data in ftime dim + ftimedim <- which(names(dim(data$data)) == 'ftime') + dims <- dim(data$data) + dims[ftimedim] <- insert_ftime + empty_array <- array(NA, dims) + data$data <- abind(empty_array, data$data, along = ftimedim) + names(dim(data$data)) <- names(dims) + # adding dates to Dates for the new NAs introduced + if ((data$Dates[[1]][2] - data$Dates[[1]][1]) == 1) { + timefreq <- 'days' + } else { + timefreq <- 'months' + warning("Time frequency of forecast time is considered monthly.") + } + start <- data$Dates[[1]] + dim(start) <- c(ftime = length(start)/dims['sdate'], sdate = dims['sdate']) + # new <- array(NA, prod(dim(data$data)[c('ftime', 'sdate')])) + # Pending fix transform to UTC when concatenaiting + data$Dates$start <- do.call(c, lapply(1:dim(start)[2], function(x) { + seq(start[1,x] - as.difftime(insert_ftime, + units = timefreq), + start[dim(start)[1],x], by = timefreq, tz = "UTC")})) } - if (!is.null(insert_ftime)) { - if (!is.numeric(insert_ftime)) { - stop("Parameter 'insert_ftime' should be an integer.") + } + if (is.null(indices)) { + if (any(split_dim %in% c('ftime', 'time', 'sdate'))) { + if (is.list(data$Dates)) { + indices <- data$Dates[[1]] } else { - if (length(insert_ftime) > 1) { - warning("Parameter 'insert_ftime' must be of length 1, and only the", - " first element will be used.") - insert_ftime <- insert_ftime[1] - } - # adding NAs at the begining of the data in ftime dim - ftimedim <- which(names(dim(data$data)) == 'ftime') - dims <- dim(data$data) - dims[ftimedim] <- insert_ftime - empty_array <- array(NA, dims) - data$data <- abind(empty_array, data$data, along = ftimedim) - names(dim(data$data)) <- names(dims) - # adding dates to Dates for the new NAs introduced - if ((data$Dates[[1]][2] - data$Dates[[1]][1]) == 1) { - timefreq <- 'days' - } else { - timefreq <- 'months' - warning("Time frequency of forecast time is considered monthly.") - } - start <- data$Dates[[1]] - dim(start) <- c(ftime = length(start)/dims['sdate'], sdate = dims['sdate']) - #new <- array(NA, prod(dim(data$data)[c('ftime', 'sdate')])) - # Pending fix transform to UTC when concatenaiting - data$Dates$start <- do.call(c, lapply(1:dim(start)[2], function(x) { - seq(start[1,x] - as.difftime(insert_ftime, - units = timefreq), - start[dim(start)[1],x], by = timefreq, tz = "UTC")})) + indices <- data$Dates } - } - if (is.null(indices)) { - if (any(split_dim %in% c('ftime', 'time', 'sdate'))) { - if (is.list(data$Dates)) { - indices <- data$Dates[[1]] - } else { - indices <- data$Dates - } - if (any(names(dim(data$data)) %in% 'sdate')) { - if (!any(names(dim(data$data)) %in% split_dim)) { - stop("Parameter 'split_dims' must be one of the dimension ", - "names in parameter 'data'.") - } - indices <- indices[1 : dim(data$data)[which(names(dim(data$data)) == - split_dim)]] + if (any(names(dim(data$data)) %in% 'sdate')) { + if (!any(names(dim(data$data)) %in% split_dim)) { + stop("Parameter 'split_dims' must be one of the dimension ", + "names in parameter 'data'.") } + indices <- indices[1 : dim(data$data)[which(names(dim(data$data)) == split_dim)]] } } - data$data <- SplitDim(data$data, split_dim = split_dim, indices = indices, + } + data$data <- SplitDim(data$data, split_dim = split_dim, indices = indices, freq = freq, new_dim_name = new_dim_name) - return(data) + return(data) } #'Function to Split Dimension #' #'@author Nuria Perez-Zanon, \email{nuria.perez@bsc.es} #' -#'@description This function split a dimension in two. The user can select the dimension to split and provide indices indicating how to split that dimension or dates and the frequency expected (monthly or by day, month and year). The user can also provide a numeric frequency indicating the length of each division. +#'@description This function split a dimension in two. The user can select the +#'dimension to split and provide indices indicating how to split that dimension +#'or dates and the frequency expected (monthly or by day, month and year). The +#'user can also provide a numeric frequency indicating the length of each division. #' -#'@param data an n-dimensional array with named dimensions -#'@param split_dim a character string indicating the name of the dimension to split -#'@param indices a vector of numeric indices or dates -#'@param freq a character string indicating the frequency: by 'day', 'month' and 'year' or 'monthly' (by default). 'month' identifies months between 1 and 12 independetly of the year they belong to, while 'monthly' differenciates months from different years. Parameter 'freq' can also be numeric indicating the length in which to subset the dimension. -#'@param new_dim_name a character string indicating the name of the new dimension. +#'@param data An n-dimensional array with named dimensions. +#'@param split_dim A character string indicating the name of the dimension to +#' split. +#'@param indices A vector of numeric indices or dates. +#'@param freq A character string indicating the frequency: by 'day', 'month' and +#' 'year' or 'monthly' (by default). 'month' identifies months between 1 and 12 +#' independetly of the year they belong to, while 'monthly' differenciates +#' months from different years. Parameter 'freq' can also be numeric indicating +#' the length in which to subset the dimension. +#'@param new_dim_name A character string indicating the name of the new +#' dimension. #'@import abind #'@importFrom ClimProjDiags Subset #'@examples -#' #'data <- 1 : 20 #'dim(data) <- c(time = 10, lat = 2) #'indices <- c(rep(1,5), rep(2,5)) @@ -125,137 +151,137 @@ CST_SplitDim <- function(data, split_dim = 'time', indices = NULL, #'@export SplitDim <- function(data, split_dim = 'time', indices, freq = 'monthly', new_dim_name = NULL) { - # check data - if (is.null(data)) { - stop("Parameter 'data' cannot be NULL.") - } - if (is.null(dim(data))) { - dim(data) = c(time = length(data)) - } - if (is.null(names(dim(data)))) { - stop("Parameter 'data' must have dimension names.") - } - dims <- dim(data) - # check split_dim - if (!is.character(split_dim)) { - stop("Parameter 'split_dim' must be a character.") - } - if (length(split_dim) > 1) { - split_dim <- split_dim[1] - warning("Parameter 'split_dim' has length greater than ", - "one and only the first element will be used.") - } - if (!any(names(dims) %in% split_dim)) { - stop("Parameter 'split_dims' must be one of the dimension ", - "names in parameter 'data'.") - } - pos_split <- which(names(dims) == split_dim) - # check indices and freq - if (is.null(indices)) { - if (!is.numeric(freq)) { - stop("Parameter 'freq' must be a integer number indicating ", - " the length of each chunk.") - } else { - if (!((dims[pos_split] / freq) %% 1 == 0)) { - stop("Parameter 'freq' must be proportional to the ", - "length of the 'split_dim' in parameter 'data'.") - } - indices <- rep(1 : (dims[pos_split] / freq), freq) - indices <- sort(indices) - repited <- sort(unique(indices)) - } - } else if (is.numeric(indices)) { - if (!is.null(freq)) { - if (freq != 'monthly') { - warning("Parameter 'freq' is not being used since ", - "parameter 'indices' is numeric.") - } - } - repited <- sort(unique(indices)) + # check data + if (is.null(data)) { + stop("Parameter 'data' cannot be NULL.") + } + if (is.null(dim(data))) { + dim(data) = c(time = length(data)) + } + if (is.null(names(dim(data)))) { + stop("Parameter 'data' must have dimension names.") + } + dims <- dim(data) + # check split_dim + if (!is.character(split_dim)) { + stop("Parameter 'split_dim' must be a character.") + } + if (length(split_dim) > 1) { + split_dim <- split_dim[1] + warning("Parameter 'split_dim' has length greater than ", + "one and only the first element will be used.") + } + if (!any(names(dims) %in% split_dim)) { + stop("Parameter 'split_dims' must be one of the dimension ", + "names in parameter 'data'.") + } + pos_split <- which(names(dims) == split_dim) + # check indices and freq + if (is.null(indices)) { + if (!is.numeric(freq)) { + stop("Parameter 'freq' must be a integer number indicating ", + " the length of each chunk.") } else { - # Indices should be Dates and freq character - if (!is.character(freq)) { - stop("Parameter 'freq' must be a character indicating ", - "how to divide the dates provided in parameter 'indices'", - ", 'monthly', 'anually' or 'daily'.") - } - if (!(any(class(indices) %in% c('POSIXct')))) { - indices <- try( { - if (is.character(indices)) { - as.POSIXct(indices) - } else { - as.POSIXct(indices) - } - }) - if ('try-error' %in% class(indices) | - sum(is.na(indices)) == length(indices)) { - stop("Dates provided in parameter 'indices' must be of class", - " 'POSIXct' or convertable to 'POSIXct'.") - } - } + if (!((dims[pos_split] / freq) %% 1 == 0)) { + stop("Parameter 'freq' must be proportional to the ", + "length of the 'split_dim' in parameter 'data'.") + } + indices <- rep(1 : (dims[pos_split] / freq), freq) + indices <- sort(indices) + repited <- sort(unique(indices)) } - if (length(indices) != dims[pos_split]) { - stop("Parameter 'indices' has different length of parameter ", - "data in the dimension supplied in 'split_dim'.") + } else if (is.numeric(indices)) { + if (!is.null(freq)) { + if (freq != 'monthly') { + warning("Parameter 'freq' is not being used since ", + "parameter 'indices' is numeric.") + } } - # check indices as dates: - if (!is.numeric(indices)) { - if (freq == 'day') { - indices <- as.numeric(strftime(indices, format = "%d")) - repited <- unique(indices) - } else if (freq == 'month') { - indices <- as.numeric(strftime(indices, format = "%m")) - repited <- unique(indices) - } else if (freq == 'year') { - indices <- as.numeric(strftime(indices, format = "%Y")) - repited <- unique(indices) - } else if (freq == 'monthly' ) { - indices <- as.numeric(strftime(indices, format = "%m%Y")) - repited <- unique(indices) - } else { - stop("Parameter 'freq' must be numeric or a character: ", - "by 'day', 'month', 'year' or 'monthly' (for ", - "distinguishable month).") - } + repited <- sort(unique(indices)) + } else { + # Indices should be Dates and freq character + if (!is.character(freq)) { + stop("Parameter 'freq' must be a character indicating ", + "how to divide the dates provided in parameter 'indices'", + ", 'monthly', 'anually' or 'daily'.") } - # check new_dim_name - if (!is.null(new_dim_name)) { - if (!is.character(new_dim_name)) { - stop("Parameter 'new_dim_name' must be character string") + if (!inherits(indices, 'POSIXct')) { + indices <- try({ + if (is.character(indices)) { + as.POSIXct(indices) + } else { + as.POSIXct(indices) } - if (length(new_dim_name) > 1) { - new_dim_name <- new_dim_name[1] - warning("Parameter 'new_dim_name' has length greater than 1 ", - "and only the first elemenst is used.") + }) + if ('try-error' %in% class(indices) | + sum(is.na(indices)) == length(indices)) { + stop("Dates provided in parameter 'indices' must be of class", + " 'POSIXct' or convertable to 'POSIXct'.") } } - max_times <- max(unlist(lapply(repited, - function(x){sum(indices == x)}))) - data <- lapply(repited, function(x) {rebuild(x, data, along = split_dim, - indices = indices, max_times)}) - data <- abind(data, along = length(dims) + 1) - if (is.character(freq)) { - names(dim(data)) <- c(names(dims), freq) + } + if (length(indices) != dims[pos_split]) { + stop("Parameter 'indices' has different length of parameter ", + "data in the dimension supplied in 'split_dim'.") + } + # check indices as dates: + if (!is.numeric(indices)) { + if (freq == 'day') { + indices <- as.numeric(strftime(indices, format = "%d")) + repited <- unique(indices) + } else if (freq == 'month') { + indices <- as.numeric(strftime(indices, format = "%m")) + repited <- unique(indices) + } else if (freq == 'year') { + indices <- as.numeric(strftime(indices, format = "%Y")) + repited <- unique(indices) + } else if (freq == 'monthly' ) { + indices <- as.numeric(strftime(indices, format = "%m%Y")) + repited <- unique(indices) } else { - names(dim(data)) <- c(names(dims), 'index') + stop("Parameter 'freq' must be numeric or a character: ", + "by 'day', 'month', 'year' or 'monthly' (for ", + "distinguishable month).") + } + } + # check new_dim_name + if (!is.null(new_dim_name)) { + if (!is.character(new_dim_name)) { + stop("Parameter 'new_dim_name' must be character string") } - if (!is.null(new_dim_name)) { - names(dim(data)) <- c(names(dims), new_dim_name) + if (length(new_dim_name) > 1) { + new_dim_name <- new_dim_name[1] + warning("Parameter 'new_dim_name' has length greater than 1 ", + "and only the first elemenst is used.") } -return(data) + } + max_times <- max(unlist(lapply(repited, + function(x){sum(indices == x)}))) + data <- lapply(repited, function(x) {rebuild(x, data, along = split_dim, + indices = indices, max_times)}) + data <- abind(data, along = length(dims) + 1) + if (is.character(freq)) { + names(dim(data)) <- c(names(dims), freq) + } else { + names(dim(data)) <- c(names(dims), 'index') + } + if (!is.null(new_dim_name)) { + names(dim(data)) <- c(names(dims), new_dim_name) + } + return(data) } rebuild <- function(x, data, along, indices, max_times) { - a <- Subset(data, along = along, indices = which(indices == x)) - pos_dim <- which(names(dim(a)) == along) - if (dim(a)[pos_dim] != max_times) { - adding <- max_times - dim(a)[pos_dim] - new_dims <- dim(a) - new_dims[pos_dim] <- adding - extra <- array(NA, dim = new_dims) - a <- abind(a, extra, along = pos_dim) - names(dim(a)) <- names(dim(data)) - } - return(a) + a <- Subset(data, along = along, indices = which(indices == x)) + pos_dim <- which(names(dim(a)) == along) + if (dim(a)[pos_dim] != max_times) { + adding <- max_times - dim(a)[pos_dim] + new_dims <- dim(a) + new_dims[pos_dim] <- adding + extra <- array(NA, dim = new_dims) + a <- abind(a, extra, along = pos_dim) + names(dim(a)) <- names(dim(data)) + } + return(a) } diff --git a/R/CST_WeatherRegimes.R b/R/CST_WeatherRegimes.R index c0c85c07db3afc3921bf155b3099b685bfe66e52..abc1fabab52073e247d2356be4abed11eee6238e 100644 --- a/R/CST_WeatherRegimes.R +++ b/R/CST_WeatherRegimes.R @@ -1,39 +1,54 @@ -#' @rdname CST_WeatherRegimes -#' @title Function for Calculating the Cluster analysis +#'@rdname CST_WeatherRegimes +#'@title Function for Calculating the Cluster analysis #' -#' @author Verónica Torralba - BSC, \email{veronica.torralba@bsc.es} +#'@author Verónica Torralba - BSC, \email{veronica.torralba@bsc.es} #' -#' @description This function computes the weather regimes from a cluster analysis. -#'It is applied on the array \code{data} in a 's2dv_cube' object. The dimensionality of this object can be also reduced -#'by using PCs obtained from the application of the #'EOFs analysis to filter the dataset. -#'The cluster analysis can be performed with the traditional k-means or those methods +#'@description This function computes the weather regimes from a cluster +#'analysis. It is applied on the array \code{data} in a 's2dv_cube' object. The +#'dimensionality of this object can be also reduced by using PCs obtained from +#'the application of the #'EOFs analysis to filter the dataset. The cluster +#'analysis can be performed with the traditional k-means or those methods #'included in the hclust (stats package). #' -#'@references Cortesi, N., V., Torralba, N., González-Reviriego, A., Soret, and F.J., Doblas-Reyes (2019). -#' Characterization of European wind speed variability using weather regimes. Climate Dynamics,53, -#' 4961–4976, doi:10.1007/s00382-019-04839-5. -#'@references Torralba, V. (2019) Seasonal climate prediction for the wind energy sector: methods and tools -#' for the development of a climate service. Thesis. Available online: \url{https://eprints.ucm.es/56841/} +#'@references Cortesi, N., V., Torralba, N., González-Reviriego, A., Soret, and +#'F.J., Doblas-Reyes (2019). Characterization of European wind speed variability +#'using weather regimes. Climate Dynamics,53, 4961–4976, doi:10.1007/s00382-019-04839-5. +#'@references Torralba, V. (2019) Seasonal climate prediction for the wind +#'energy sector: methods and tools for the development of a climate service. +#'Thesis. Available online: \url{https://eprints.ucm.es/56841/}. #' -#'@param data a 's2dv_cube' object -#'@param ncenters Number of clusters to be calculated with the clustering function. -#'@param EOFs Whether to compute the EOFs (default = 'TRUE') or not (FALSE) to filter the data. -#'@param neofs number of modes to be kept (default = 30). -#'@param varThreshold Value with the percentage of variance to be explained by the PCs. -#' Only sufficient PCs to explain this much variance will be used in the clustering. -#'@param method Different options to estimate the clusters. The most traditional approach is the k-means analysis (default=’kmeans’) -#'but the function also support the different methods included in the hclust . These methods are: -#'"ward.D", "ward.D2", "single", "complete", "average" (= UPGMA), "mcquitty" (= WPGMA), "median" (= WPGMC) or "centroid" (= UPGMC). -#' For more details about these methods see the hclust function documentation included in the stats package. -#'@param iter.max Parameter to select the maximum number of iterations allowed (Only if method='kmeans' is selected). -#'@param nstart Parameter for the cluster analysis determining how many random sets to choose (Only if method='kmeans' is selected). +#'@param data An 's2dv_cube' object +#'@param ncenters Number of clusters to be calculated with the clustering +#' function. +#'@param EOFs Whether to compute the EOFs (default = 'TRUE') or not (FALSE) to +#' filter the data. +#'@param neofs Number of modes to be kept (default = 30). +#'@param varThreshold Value with the percentage of variance to be explained by +#' the PCs. Only sufficient PCs to explain this much variance will be used in +#' the clustering. +#'@param method Different options to estimate the clusters. The most traditional +#' approach is the k-means analysis (default=’kmeans’) but the function also +#' support the different methods included in the hclust . These methods are: +#' "ward.D", "ward.D2", "single", "complete", "average" (= UPGMA), "mcquitty" +#' (= WPGMA), "median" (= WPGMC) or "centroid" (= UPGMC). For more details +#' about these methods see the hclust function documentation included in the +#' stats package. +#'@param iter.max Parameter to select the maximum number of iterations allowed +#' (Only if method='kmeans' is selected). +#'@param nstart Parameter for the cluster analysis determining how many random +#' sets to choose (Only if method='kmeans' is selected). #'@param ncores The number of multicore threads to use for parallel computation. -#'@return A list with two elements \code{$data} (a 's2dv_cube' object containing the composites cluster=1,..,K for case (*1) -# or only k=1 for any specific cluster, i.e., case (*2)) and \code{$statistics} that includes -#' \code{$pvalue} (array with the same structure as \code{$data} containing the pvalue of the composites obtained through a t-test that accounts for the serial dependence.), -#' \code{cluster} (A matrix or vector with integers (from 1:k) indicating the cluster to which each time step is allocated.), -#' \code{persistence} (Percentage of days in a month/season before a cluster is replaced for a new one (only if method=’kmeans’ has been selected.)), -#' \code{frequency} (Percentage of days in a month/season belonging to each cluster (only if method=’kmeans’ has been selected).), +#'@return A list with two elements \code{$data} (a 's2dv_cube' object containing +#'the composites cluster = 1,..,K for case (*1) or only k = 1 for any specific +#'cluster, i.e., case (*2)) and \code{$statistics} that includes \code{$pvalue} +#'(array with the same structure as \code{$data} containing the pvalue of the +#'composites obtained through a t-test that accounts for the serial dependence.), +#'\code{cluster} (A matrix or vector with integers (from 1:k) indicating the +#'cluster to which each time step is allocated.), \code{persistence} (Percentage +#'of days in a month/season before a cluster is replaced for a new one (only if +#'method=’kmeans’ has been selected.)), \code{frequency} (Percentage of days in +#'a month/season belonging to each cluster (only if method=’kmeans’ has been +#'selected).), #'@importFrom s2dv EOF #'@import multiApply #'@examples @@ -42,13 +57,12 @@ #'res2 <- CST_WeatherRegimes(data = lonlat_temp$obs, EOFs = TRUE, ncenters = 3) #'} #'@export -#' CST_WeatherRegimes <- function(data, ncenters = NULL, - EOFs = TRUE, neofs = 30, - varThreshold = NULL, - method = "kmeans", - iter.max = 100, nstart = 30, - ncores = NULL) { + EOFs = TRUE, neofs = 30, + varThreshold = NULL, + method = "kmeans", + iter.max = 100, nstart = 30, + ncores = NULL) { if (!inherits(data, 's2dv_cube')) { stop("Parameter 'data' must be of the class 's2dv_cube', ", "as output by CSTools::CST_Load.") @@ -69,55 +83,69 @@ CST_WeatherRegimes <- function(data, ncenters = NULL, return(data) } -#' @rdname WeatherRegimes -#' @title Function for Calculating the Cluster analysis +#'@rdname WeatherRegimes +#'@title Function for Calculating the Cluster analysis #' -#' @author Verónica Torralba - BSC, \email{veronica.torralba@bsc.es} +#'@author Verónica Torralba - BSC, \email{veronica.torralba@bsc.es} #' -#' @description This function computes the weather regimes from a cluster analysis. -#'It can be applied over the dataset with dimensions -#'c(year/month, month/day, lon, lat), or by using PCs obtained from the application of the -#'EOFs analysis to filter the dataset. -#'The cluster analysis can be performed with the traditional k-means or those methods -#'included in the hclust (stats package). +#'@description This function computes the weather regimes from a cluster analysis. +#'It can be applied over the dataset with dimensions c(year/month, month/day, +#'lon, lat), or by using PCs obtained from the application of the EOFs analysis +#'to filter the dataset. The cluster analysis can be performed with the +#'traditional k-means or those methods included in the hclust (stats package). #' -#'@references Cortesi, N., V., Torralba, N., González-Reviriego, A., Soret, and F.J., Doblas-Reyes (2019). -#' Characterization of European wind speed variability using weather regimes. Climate Dynamics,53, -#' 4961–4976, doi:10.1007/s00382-019-04839-5. -#'@references Torralba, V. (2019) Seasonal climate prediction for the wind energy sector: methods and tools -#' for the development of a climate service. Thesis. Available online: \url{https://eprints.ucm.es/56841/} +#'@references Cortesi, N., V., Torralba, N., González-Reviriego, A., Soret, and +#'F.J., Doblas-Reyes (2019). Characterization of European wind speed variability +#'using weather regimes. Climate Dynamics,53, 4961–4976, doi:10.1007/s00382-019-04839-5. +#'@references Torralba, V. (2019) Seasonal climate prediction for the wind +#'energy sector: methods and tools for the development of a climate service. +#'Thesis. Available online: \url{https://eprints.ucm.es/56841/} #' -#'@param data an array containing anomalies with named dimensions with at least start date 'sdate', forecast time 'ftime', latitude 'lat' and longitude 'lon'. -#'@param ncenters Number of clusters to be calculated with the clustering function. -#'@param EOFs Whether to compute the EOFs (default = 'TRUE') or not (FALSE) to filter the data. -#'@param neofs number of modes to be kept only if EOFs = TRUE has been selected. (default = 30). -#'@param varThreshold Value with the percentage of variance to be explained by the PCs. -#' Only sufficient PCs to explain this much variance will be used in the clustering. +#'@param data An array containing anomalies with named dimensions with at least +#' start date 'sdate', forecast time 'ftime', latitude 'lat' and longitude +#' 'lon'. +#'@param ncenters Number of clusters to be calculated with the clustering +#' function. +#'@param EOFs Whether to compute the EOFs (default = 'TRUE') or not (FALSE) to +#' filter the data. +#'@param neofs Number of modes to be kept only if EOFs = TRUE has been selected. +#' (default = 30). +#'@param varThreshold Value with the percentage of variance to be explained by +#' the PCs. Only sufficient PCs to explain this much variance will be used in +#' the clustering. #'@param lon Vector of longitudes. #'@param lat Vector of latitudes. -#'@param method Different options to estimate the clusters. The most traditional approach is the k-means analysis (default=’kmeans’) -#'but the function also support the different methods included in the hclust . These methods are: -#'"ward.D", "ward.D2", "single", "complete", "average" (= UPGMA), "mcquitty" (= WPGMA), "median" (= WPGMC) or "centroid" (= UPGMC). -#' For more details about these methods see the hclust function documentation included in the stats package. -#'@param iter.max Parameter to select the maximum number of iterations allowed (Only if method='kmeans' is selected). -#'@param nstart Parameter for the cluster analysis determining how many random sets to choose (Only if method='kmeans' is selected). +#'@param method Different options to estimate the clusters. The most traditional +#' approach is the k-means analysis (default=’kmeans’) but the function also +#' support the different methods included in the hclust . These methods are: +#' "ward.D", "ward.D2", "single", "complete", "average" (= UPGMA), "mcquitty" +#' (= WPGMA), "median" (= WPGMC) or "centroid" (= UPGMC). For more details +#' about these methods see the hclust function documentation included in the +#' stats package. +#'@param iter.max Parameter to select the maximum number of iterations allowed +#' (Only if method = 'kmeans' is selected). +#'@param nstart Parameter for the cluster analysis determining how many random +#' sets to choose (Only if method='kmeans' is selected). #'@param ncores The number of multicore threads to use for parallel computation. -#'@return A list with elements \code{$composite} (array with at least 3-d ('lat', 'lon', 'cluster') containing the composites k=1,..,K for case (*1) -# or only k=1 for any specific cluster, i.e., case (*2)), -#' \code{pvalue} (array with at least 3-d ('lat','lon','cluster') with the pvalue of the composites obtained through a t-test that accounts for the serial -# dependence of the data with the same structure as Composite.), -#' \code{cluster} (A matrix or vector with integers (from 1:k) indicating the cluster to which each time step is allocated.), -#' \code{persistence} (Percentage of days in a month/season before a cluster is replaced for a new one (only if method=’kmeans’ has been selected.)), -#' \code{frequency} (Percentage of days in a month/season belonging to each cluster (only if method=’kmeans’ has been selected).), +#'@return A list with elements \code{$composite} (array with at least 3-d ('lat', +#''lon', 'cluster') containing the composites k = 1,..,K for case (*1) or only k = 1 +#'for any specific cluster, i.e., case (*2)), \code{pvalue} (array with at least +#'3-d ('lat','lon','cluster') with the pvalue of the composites obtained through +#'a t-test that accounts for the serial dependence of the data with the same +#'structure as Composite.), \code{cluster} (A matrix or vector with integers +#'(from 1:k) indicating the cluster to which each time step is allocated.), +#'\code{persistence} (Percentage of days in a month/season before a cluster is +#'replaced for a new one (only if method=’kmeans’ has been selected.)), +#'\code{frequency} (Percentage of days in a month/season belonging to each +#'cluster (only if method=’kmeans’ has been selected).), #'@importFrom s2dv EOF #'@import multiApply #'@examples #'\dontrun{ #'res <- WeatherRegime(data = lonlat_temp$obs$data, lat = lonlat_temp$obs$lat, -#' EOFs = FALSE, ncenters = 4) +#' EOFs = FALSE, ncenters = 4) #'} #'@export - WeatherRegime <- function(data, ncenters = NULL, EOFs = TRUE,neofs = 30, varThreshold = NULL, lon = NULL, diff --git a/R/PlotForecastPDF.R b/R/PlotForecastPDF.R index 5cb90c16ce4ebbc11dbb3f81738588746421d284..11122a7e537b1ec9135411019956b1dba58de8d7 100644 --- a/R/PlotForecastPDF.R +++ b/R/PlotForecastPDF.R @@ -54,14 +54,8 @@ #'@importFrom plyr dlply #'@importFrom s2dv InsertDim #'@examples -#'fcsts <- data.frame(fcst1 = rnorm(10), fcst2 = rnorm(10, 0.5, 1.2), -#' fcst3 = rnorm(10, -0.5, 0.9)) +#'fcsts <- data.frame(fcst1 = rnorm(10), fcst2 = rnorm(10, 0.5, 1.2)) #'PlotForecastPDF(fcsts,c(-1,1)) -#'\donttest{ -#'fcsts2 <- array(rnorm(100), dim = c(member = 20, fcst = 5)) -#'PlotForecastPDF(fcsts2, c(-0.66, 0.66), extreme.limits = c(-1.2, 1.2), -#' fcst.names = paste0('random fcst ', 1 : 5), obs = 0.7) -#'} #'@export PlotForecastPDF <- function(fcst, tercile.limits, extreme.limits = NULL, obs = NULL, plotfile = NULL, title = "Set a title", var.name = "Varname (units)", diff --git a/R/PlotMostLikelyQuantileMap.R b/R/PlotMostLikelyQuantileMap.R index 31cde14f5ecd5e0caa3771804ac34376cfa9a2f3..3a146b92b533eb5854088bd5df6da95873b9b5b8 100644 --- a/R/PlotMostLikelyQuantileMap.R +++ b/R/PlotMostLikelyQuantileMap.R @@ -1,21 +1,45 @@ #'Plot Maps of Most Likely Quantiles #' -#'@author Veronica Torralba, \email{veronica.torralba@bsc.es}, Nicolau Manubens, \email{nicolau.manubens@bsc.es} -#'@description This function receives as main input (via the parameter \code{probs}) a collection of longitude-latitude maps, each containing the probabilities (from 0 to 1) of the different grid cells of belonging to a category. As many categories as maps provided as inputs are understood to exist. The maps of probabilities must be provided on a common rectangular regular grid, and a vector with the longitudes and a vector with the latitudes of the grid must be provided. The input maps can be provided in two forms, either as a list of multiple two-dimensional arrays (one for each category) or as a three-dimensional array, where one of the dimensions corresponds to the different categories. +#'@author Veronica Torralba, \email{veronica.torralba@bsc.es}, Nicolau Manubens, +#'\email{nicolau.manubens@bsc.es} +#'@description This function receives as main input (via the parameter +#'\code{probs}) a collection of longitude-latitude maps, each containing the +#'probabilities (from 0 to 1) of the different grid cells of belonging to a +#'category. As many categories as maps provided as inputs are understood to +#'exist. The maps of probabilities must be provided on a common rectangular +#'regular grid, and a vector with the longitudes and a vector with the latitudes +#'of the grid must be provided. The input maps can be provided in two forms, +#'either as a list of multiple two-dimensional arrays (one for each category) or +#'as a three-dimensional array, where one of the dimensions corresponds to the +#'different categories. #' -#'@param probs a list of bi-dimensional arrays with the named dimensions 'latitude' (or 'lat') and 'longitude' (or 'lon'), with equal size and in the same order, or a single tri-dimensional array with an additional dimension (e.g. 'bin') for the different categories. The arrays must contain probability values between 0 and 1, and the probabilities for all categories of a grid cell should not exceed 1 when added. -#'@param lon a numeric vector with the longitudes of the map grid, in the same order as the values along the corresponding dimension in \code{probs}. -#'@param lat a numeric vector with the latitudes of the map grid, in the same order as the values along the corresponding dimension in \code{probs}. -#'@param cat_dim the name of the dimension along which the different categories are stored in \code{probs}. This only applies if \code{probs} is provided in the form of 3-dimensional array. The default expected name is 'bin'. -#'@param bar_titles vector of character strings with the names to be drawn on top of the color bar for each of the categories. As many titles as categories provided in \code{probs} must be provided. -#'@param col_unknown_cat character string with a colour representation of the colour to be used to paint the cells for which no category can be clearly assigned. Takes the value 'white' by default. +#'@param probs A list of bi-dimensional arrays with the named dimensions +#' 'latitude' (or 'lat') and 'longitude' (or 'lon'), with equal size and in the +#' same order, or a single tri-dimensional array with an additional dimension +#' (e.g. 'bin') for the different categories. The arrays must contain +#' probability values between 0 and 1, and the probabilities for all categories +#' of a grid cell should not exceed 1 when added. +#'@param lon A numeric vector with the longitudes of the map grid, in the same +#' order as the values along the corresponding dimension in \code{probs}. +#'@param lat A numeric vector with the latitudes of the map grid, in the same +#' order as the values along the corresponding dimension in \code{probs}. +#'@param cat_dim The name of the dimension along which the different categories +#' are stored in \code{probs}. This only applies if \code{probs} is provided in +#' the form of 3-dimensional array. The default expected name is 'bin'. +#'@param bar_titles Vector of character strings with the names to be drawn on +#' top of the color bar for each of the categories. As many titles as +#' categories provided in \code{probs} must be provided. +#'@param col_unknown_cat Character string with a colour representation of the +#' colour to be used to paint the cells for which no category can be clearly +#' assigned. Takes the value 'white' by default. #'@param drawleg Where to draw the common colour bar. Can take values TRUE, #' FALSE or:\cr #' 'up', 'u', 'U', 'top', 't', 'T', 'north', 'n', 'N'\cr #' 'down', 'd', 'D', 'bottom', 'b', 'B', 'south', 's', 'S' (default)\cr #' 'right', 'r', 'R', 'east', 'e', 'E'\cr #' 'left', 'l', 'L', 'west', 'w', 'W' -#'@param ... additional parameters to be sent to \code{PlotCombinedMap} and \code{PlotEquiMap}. +#'@param ... Additional parameters to be sent to \code{PlotCombinedMap} and +#' \code{PlotEquiMap}. #'@seealso \code{PlotCombinedMap} and \code{PlotEquiMap} #' #'@importFrom maps map diff --git a/R/PlotPDFsOLE.R b/R/PlotPDFsOLE.R index 25c669a471bb96392ebfea4cc614764f67e07a1f..58e0bf969a9c6615929259c29700585e1ff05a07 100644 --- a/R/PlotPDFsOLE.R +++ b/R/PlotPDFsOLE.R @@ -1,63 +1,48 @@ -#' Plotting two probability density gaussian functions and the optimal linear -#' estimation (OLE) as result of combining them. +#'Plotting two probability density gaussian functions and the optimal linear +#'estimation (OLE) as result of combining them. #' -#' @author Eroteida Sanchez-Garcia - AEMET, //email{esanchezg@aemet.es} +#'@author Eroteida Sanchez-Garcia - AEMET, //email{esanchezg@aemet.es} #' -#' @description This function plots two probability density gaussian functions -#' and the optimal linear estimation (OLE) as result of combining them. +#'@description This function plots two probability density gaussian functions +#'and the optimal linear estimation (OLE) as result of combining them. #' -#' @param pdf_1 A numeric array with a dimension named 'statistic', containg -#' two parameters: mean' and 'standard deviation' of the first gaussian pdf -#' to combining. -#' @param pdf_2 A numeric array with a dimension named 'statistic', containg -#' two parameters: mean' and 'standard deviation' of the second gaussian pdf +#'@param pdf_1 A numeric array with a dimension named 'statistic', containg +#' two parameters: mean' and 'standard deviation' of the first gaussian pdf #' to combining. -#' @param nsigma (optional) A numeric value for setting the limits of X axis. -#' (Default nsigma = 3). -#' @param legendPos (optional) A character value for setting the position of the -#' legend ("bottom", "top", "right" or "left")(Default 'bottom'). -#' @param legendSize (optional) A numeric value for setting the size of the -#' legend text. (Default 1.0). -#' @param plotfile (optional) A filename where the plot will be saved. -#' (Default: the plot is not saved). -#' @param width (optional) A numeric value indicating the plot width in -#' units ("in", "cm", or "mm"). (Default width = 30). -#' @param height (optional) A numeric value indicating the plot height. -#' (Default height = 15). -#' @param units (optional) A character value indicating the plot size -#' unit. (Default units = 'cm'). -#' @param dpi (optional) A numeric value indicating the plot resolution. -#' (Default dpi = 300). -#' -#' @return PlotPDFsOLE() returns a ggplot object containing the plot. -#' -#' @import ggplot2 -#' -#' @examples -#' # Example 1 -#' pdf_1 <- c(1.1,0.6) -#' attr(pdf_1, "name") <- "NAO1" -#' dim(pdf_1) <- c(statistic = 2) -#' pdf_2 <- c(1,0.5) -#' attr(pdf_2, "name") <- "NAO2" -#' dim(pdf_2) <- c(statistic = 2) -#' -#' PlotPDFsOLE(pdf_1, pdf_2) -#' -#' # Example 2 -#' Glosea5PDF <- c(2.25, 0.67) -#' attr(Glosea5PDF, "name") <- "Glosea5" -#' dim(Glosea5PDF) <- c(statistic = 2) -#' ECMWFPDF <- c(2.38, 0.61) -#' attr(ECMWFPDF, "name") <- "ECMWF" -#' dim(ECMWFPDF) <- c(statistic = 2) -#' MFPDF <- c(4.52, 0.34) -#' attr(MFPDF, "name") <- "MF" -#' dim(MFPDF) <- c(statistic = 2) -#' PlotPDFsOLE(pdf_1 = Glosea5PDF, pdf_2 = ECMWFPDF, legendPos = 'left') -#' PlotPDFsOLE(pdf_1 = Glosea5PDF, pdf_2 = MFPDF, legendPos = 'top') -#' PlotPDFsOLE(pdf_1 = ECMWFPDF, pdf_2 = MFPDF, legendSize = 1.2) - +#'@param pdf_2 A numeric array with a dimension named 'statistic', containg +#' two parameters: mean' and 'standard deviation' of the second gaussian pdf +#' to combining. +#'@param nsigma (optional) A numeric value for setting the limits of X axis. +#' (Default nsigma = 3). +#'@param legendPos (optional) A character value for setting the position of the +#' legend ("bottom", "top", "right" or "left")(Default 'bottom'). +#'@param legendSize (optional) A numeric value for setting the size of the +#' legend text. (Default 1.0). +#'@param plotfile (optional) A filename where the plot will be saved. +#' (Default: the plot is not saved). +#'@param width (optional) A numeric value indicating the plot width in +#' units ("in", "cm", or "mm"). (Default width = 30). +#'@param height (optional) A numeric value indicating the plot height. +#' (Default height = 15). +#'@param units (optional) A character value indicating the plot size +#' unit. (Default units = 'cm'). +#'@param dpi (optional) A numeric value indicating the plot resolution. +#' (Default dpi = 300). +#' +#'@return PlotPDFsOLE() returns a ggplot object containing the plot. +#' +#'@import ggplot2 +#' +#'@examples +#'# Example 1 +#'pdf_1 <- c(1.1,0.6) +#'attr(pdf_1, "name") <- "NAO1" +#'dim(pdf_1) <- c(statistic = 2) +#'pdf_2 <- c(1,0.5) +#'attr(pdf_2, "name") <- "NAO2" +#'dim(pdf_2) <- c(statistic = 2) +#' +#'PlotPDFsOLE(pdf_1, pdf_2) #'@export PlotPDFsOLE <- function(pdf_1, pdf_2, nsigma = 3, legendPos = 'bottom', legendSize = 1.0, plotfile = NULL, width = 30, diff --git a/R/PlotTriangles4Categories.R b/R/PlotTriangles4Categories.R index 16abb421a24bc8bcb0e4be891c5945132e92cb8b..c851c9e0d7faf1e1acf07ccbee31972aee5e2f32 100644 --- a/R/PlotTriangles4Categories.R +++ b/R/PlotTriangles4Categories.R @@ -1,11 +1,12 @@ #'Function to convert any 3-d numerical array to a grid of coloured triangles. #' #'This function converts a 3-d numerical data array into a coloured -#'grid with triangles. It is useful for a slide or article to present tabular results as -#'colors instead of numbers. This can be used to compare the outputs of two or four categories ( -#'e.g. modes of variability, clusters, or forecast systems). +#'grid with triangles. It is useful for a slide or article to present tabular +#'results as colors instead of numbers. This can be used to compare the outputs +#'of two or four categories (e.g. modes of variability, clusters, or forecast +#'systems). #' -#'@param data array with three named dimensions: 'dimx', 'dimy', 'dimcat', +#'@param data Array with three named dimensions: 'dimx', 'dimy', 'dimcat', #' containing the values to be displayed in a coloured image with triangles. #'@param brks A vector of the color bar intervals. The length must be one more #' than the parameter 'cols'. Use ColorBar() to generate default values. @@ -13,14 +14,13 @@ #' must be one less than the parameter 'brks'. Use ColorBar() to generate #' default values. #'@param toptitle A string of the title of the grid. Set NULL as default. -#'@param sig_data logical array with the same dimensions as 'data' to add layers +#'@param sig_data Logical array with the same dimensions as 'data' to add layers #' to the plot. A value of TRUE at a grid cell will draw a dot/symbol on the #' corresponding triangle of the plot. Set NULL as default. -#'@param pch_sig symbol to be used to represent sig_data. Takes 18 -#' (diamond) by default. See 'pch' in par() for additional -#' accepted options. -#'@param col_sig colour of the symbol to represent sig_data. -#'@param cex_sig parameter to increase/reduce the size of the symbols used +#'@param pch_sig Symbol to be used to represent sig_data. Takes 18 +#' (diamond) by default. See 'pch' in par() for additional accepted options. +#'@param col_sig Colour of the symbol to represent sig_data. +#'@param cex_sig Parameter to increase/reduce the size of the symbols used #' to represent sig_data. #'@param xlab A logical value (TRUE) indicating if xlabels should be plotted #'@param ylab A logical value (TRUE) indicating if ylabels should be plotted @@ -37,18 +37,21 @@ #'@param lab_legend A vector of labels indicating what is represented in each #'category (i.e. triangle). Set the sequence from 1 to the length of #' the categories (2 or 4). -#'@param cex_leg a number to indicate the increase/reductuion of the lab_legend used -#' to represent sig_data. -#'@param col_leg color of the legend (triangles). -#'@param cex_axis a number to indicate the increase/reduction of the axis labels. +#'@param cex_leg A number to indicate the increase/reductuion of the lab_legend +#' used to represent sig_data. +#'@param col_leg Color of the legend (triangles). +#'@param cex_axis A number to indicate the increase/reduction of the axis labels. #'@param fileout A string of full directory path and file name indicating where #' to save the plot. If not specified (default), a graphics device will pop up. -#'@param mar A numerical vector of the form c(bottom, left, top, right) which gives the number of lines of margin to be specified on the four sides of the plot. +#'@param mar A numerical vector of the form c(bottom, left, top, right) which +#' gives the number of lines of margin to be specified on the four sides of the +#' plot. #'@param size_units A string indicating the units of the size of the device #' (file or window) to plot in. Set 'px' as default. See ?Devices and the #' creator function of the corresponding device. -#'@param res A positive number indicating resolution of the device (file or window) -#' to plot in. See ?Devices and the creator function of the corresponding device. +#'@param res A positive number indicating resolution of the device (file or +#' window) to plot in. See ?Devices and the creator function of the +#' corresponding device. #'@param figure.width a numeric value to control the width of the plot. #'@param ... The additional parameters to be passed to function ColorBar() in #' s2dv for color legend creation. @@ -58,19 +61,17 @@ #'1.0 - 2020-10 (V.Torralba, \email{veronica.torralba@bsc.es}) - Original code #' #'@examples -#'#Example with random data -#' arr1<- arr1<- array(runif(n = 12 * 7 * 4, min=-1, max=1),dim = c(12,7,4)) -#' names(dim(arr1)) <- c('dimx','dimy','dimcat') -#'arr2<- array(TRUE,dim = dim(arr1)) -#'arr2[which(arr1 < 0.3)] = FALSE +#'# Example with random data +#'arr1 <- array(runif(n = 4 * 5 * 4, min = -1, max = 1), dim = c(4,5,4)) +#'names(dim(arr1)) <- c('dimx', 'dimy', 'dimcat') +#'arr2 <- array(TRUE, dim = dim(arr1)) +#'arr2[which(arr1 < 0.3)] <- FALSE #'PlotTriangles4Categories(data = arr1, -#' cols = c('white','#fef0d9','#fdd49e','#fdbb84','#fc8d59', -#' '#e34a33','#b30000', '#7f0000'), -#' brks = c(-1, 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 1), -#' lab_legend = c('NAO+', 'BL','AR','NAO-'), -#' xtitle = "Target month", ytitle = "Lead time", -#' xlabels = c("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", -#' "Aug", "Sep", "Oct", "Nov", "Dec")) +#' cols = c('white','#fef0d9','#fdd49e','#fdbb84','#fc8d59'), +#' brks = c(-1, 0, 0.1, 0.2, 0.3, 0.4), +#' lab_legend = c('NAO+', 'BL','AR','NAO-'), +#' xtitle = "Target month", ytitle = "Lead time", +#' xlabels = c("Jan", "Feb", "Mar", "Apr")) #'@importFrom grDevices dev.new dev.off dev.cur #'@importFrom graphics plot points polygon text title axis #'@importFrom RColorBrewer brewer.pal diff --git a/R/Predictability.R b/R/Predictability.R index 12cd6b410f26b197da67df65e82f42f626d29668..ae063651256842e202eef124548fc2a61d8f6fed 100644 --- a/R/Predictability.R +++ b/R/Predictability.R @@ -16,18 +16,17 @@ #'@references Faranda, D., Alvarez-Castro, M.C., Messori, G., Rodriguez, D., #'and Yiou, P. (2019). The hammam effect or how a warm ocean enhances large #'scale atmospheric predictability.Nature Communications, 10(1), 1316. -#'DOI = https://doi.org/10.1038/s41467-019-09305-8 " +#'DOI = \url{https://doi.org/10.1038/s41467-019-09305-8} " #'@references Faranda, D., Gabriele Messori and Pascal Yiou. (2017). -#' Dynamical proxies of North Atlantic predictability and extremes. -#' Scientific Reports, 7-41278, 2017. +#'Dynamical proxies of North Atlantic predictability and extremes. +#'Scientific Reports, 7-41278, 2017. #' #'@param dim An array of N named dimensions containing the local dimension as -#'the output of CST_ProxiesAttractor or ProxiesAttractor. -# +#' the output of CST_ProxiesAttractor or ProxiesAttractor. #'@param theta An array of N named dimensions containing the inverse of the -#'persistence 'theta' as the output of CST_ProxiesAttractor or ProxiesAttractor. -#' -#'@param ncores The number of cores to use in parallel computation +#' persistence 'theta' as the output of CST_ProxiesAttractor or +#' ProxiesAttractor. +#'@param ncores The number of cores to use in parallel computation. #' #'@return A list of length 2: #' \itemize{ @@ -59,7 +58,6 @@ #' attractor <- ProxiesAttractor(dat = m, quanti = 0.60) #' predyn <- Predictability(dim = attractor$dim, theta = attractor$theta) #'@export -#' Predictability<- function(dim, theta, ncores = NULL) { # if (!inherits(dim, 's2dv_cube')) { # stop("Parameter 'dim' must be of the class 's2dv_cube', ", diff --git a/man/AdamontQQCorr.Rd b/man/AdamontQQCorr.Rd index b6442f45456d3ea9dcb1dad3aff2cc088e1794f7..52f78e1c43b802a49a0bd7742f011efc95d56aa5 100644 --- a/man/AdamontQQCorr.Rd +++ b/man/AdamontQQCorr.Rd @@ -18,38 +18,38 @@ AdamontQQCorr( ) } \arguments{ -\item{exp}{array with named dimensions (such as \code{$data} array of -experiment data from an object of class \code{s2dv_cube})} +\item{exp}{Array with named dimensions (such as \code{$data} array of +experiment data from an object of class \code{s2dv_cube}).} -\item{wt_exp}{corresponding weather types (same dimensions as \code{exp} but -lat/lon)} +\item{wt_exp}{Corresponding weather types (same dimensions as \code{exp} but +lat/lon).} -\item{obs}{array with named dimensions with reference data (can also be +\item{obs}{Array with named dimensions with reference data (can also be \code{$data} array of class \code{s2dv_cube}). lat/lon dimensions can differ from \code{exp} if non rectilinear latlon grids are used, in which case -regrid should be set to TRUE and .NearestNeighbors \code{NN} output should be -provided} +regrid should be set to TRUE and .NearestNeighbors \code{NN} output should +be provided.} -\item{wt_obs}{corresponding weather types (same dimensions as \code{obs} but -lat/lon)} +\item{wt_obs}{Corresponding weather types (same dimensions as \code{obs} but +lat/lon).} -\item{corrdims}{list of dimensions in \code{exp} for which quantile mapping -correction is applied} +\item{corrdims}{List of dimensions in \code{exp} for which quantile mapping +correction is applied.} -\item{londim}{character name of longitude dimension in \code{exp} and -\code{obs}} +\item{londim}{Character name of longitude dimension in \code{exp} and +\code{obs}.} -\item{latdim}{character name of latitude dimension in \code{exp} and -\code{obs}} +\item{latdim}{Character name of latitude dimension in \code{exp} and +\code{obs}.} -\item{regrid}{(optional) boolean indicating whether .NearestNeighbors -regridding is needed} +\item{regrid}{(optional) Boolean indicating whether .NearestNeighbors +regridding is needed.} -\item{NN}{(optional, if regrid=TRUE) list (output from .NearestNeighbors) -maps (nlat, nlon) onto (nlat_o, nlon_o)} +\item{NN}{(optional, if regrid = TRUE) List (output from .NearestNeighbors) +maps (nlat, nlon) onto (nlat_o, nlon_o).} } \value{ -an array (such as \code{$data} array from an object of class +An array (such as \code{$data} array from an object of class \code{s2dv_cube}) with named dimensions, containing experiment data on the lat/lon grid of \code{obs} array, corrected by quantile mapping depending on the weather types \code{wt_exp} @@ -62,12 +62,12 @@ typically provided by reanalysis data. \examples{ \dontrun{ wt_exp <- sample(1:3, 15*6*3, replace=T) -dim(wt_exp) <- c(dataset=1, member=15, sdate=6, ftime=3) -wt_obs <- sample(1:3, 6*3, replace=T) -dim(wt_obs) <- c(dataset=1, member=1, sdate=6, ftime=3) -exp_corr <- AdamontQQCorr(exp=lonlat_temp$exp$data, wt_exp=wt_exp, - obs=lonlat_temp$obs$data, wt_obs=wt_obs, - corrdims = c('dataset','member','sdate','ftime')) +dim(wt_exp) <- c(dataset = 1, member = 15, sdate = 6, ftime = 3) +wt_obs <- sample(1:3, 6*3, replace = T) +dim(wt_obs) <- c(dataset = 1, member = 1, sdate = 6, ftime = 3) +exp_corr <- AdamontQQCorr(exp = lonlat_temp$exp$data, wt_exp = wt_exp, + obs = lonlat_temp$obs$data, wt_obs = wt_obs, + corrdims = c('dataset','member','sdate','ftime')) } } \author{ diff --git a/man/Analogs.Rd b/man/Analogs.Rd index a7addc73e5bf4936c06e29be410841aae5519619..72f40425f2dee67c61a5750b5304f35d45da13eb 100644 --- a/man/Analogs.Rd +++ b/man/Analogs.Rd @@ -37,11 +37,11 @@ the same latitudinal and longitudinal dimensions as parameter 'expL' and a single temporal dimension with the maximum number of available observations.} \item{time_obsL}{A character string indicating the date of the observations -in the format "dd/mm/yyyy". Reference time to search for analogs.} +in the format "dd-mm-yyyy". Reference time to search for analogs.} \item{time_expL}{An array of N named dimensions (coinciding with time dimensions in expL) of character string(s) indicating the date(s) of the -experiment in the format "dd/mm/yyyy". Time(s) to find the analogs.} +experiment in the format "dd-mm-yyyy". Time(s) to find the analogs.} \item{lonL}{A vector containing the longitude of parameter 'expL'.} diff --git a/man/BEI_PDFBest.Rd b/man/BEI_PDFBest.Rd index 0ba24a8487daf4c3f47462b96ac7fbbe829d0700..7beba37206c36ed6d145a5b464e680d8d222a28a 100644 --- a/man/BEI_PDFBest.Rd +++ b/man/BEI_PDFBest.Rd @@ -23,43 +23,47 @@ which must be greater than 2.} \item{index_hind1}{Index (e.g. NAO index) array from a SFS (named SFS1) with at least two dimensions (time , member) or (time, statistic). The temporal dimension, by default 'time', must be greater than 2. -The dimension 'member' must be greater than 1. -The dimension 'statistic' must be equal to 2, for containing the two paramenters of -a normal distribution (mean and sd) representing the ensemble of a SFS. -It is not possible to have the dimension 'member' and 'statistic' at the same time.} +The dimension 'member' must be greater than 1. The dimension 'statistic' +must be equal to 2, for containing the two paramenters of a normal +distribution (mean and sd) representing the ensemble of a SFS. It is not +possible to have the dimension 'member' and 'statistic' +at the same time.} \item{index_hind2}{Index (e.g. NAO index) array from a SFS (named SFS2) with at least two dimensions (time , member) or (time, statistic). The temporal dimension, by default 'time', must be greater than 2. The dimension 'member' must be greater than 1. -The dimension 'statistic' must be equal to 2, for containing the two paramenters of -a normal distribution (mean and sd) representing the ensemble of a SFS. -It is not possible to have the dimension 'member' and 'statistic' together.} +The dimension 'statistic' must be equal to 2, for containing the two +paramenters of a normal distribution (mean and sd) representing the ensemble +of a SFS. It is not possible to have the dimension 'member' and 'statistic' +together.} -\item{index_fcst1}{(optional, default = NULL) Index (e.g. NAO index) array from forescating of SFS1 -with at least two dimensions (time , member) or (time, statistic). -The temporal dimension, by default 'time', must be equal to 1, the forecast year target. -The dimension 'member' must be greater than 1. -The dimension 'statistic' must be equal to 2, for containing the two paramenters of -a normal distribution (mean and sd) representing the ensemble of a SFS. -It is not possible to have the dimension 'member' and 'statistic' together.} +\item{index_fcst1}{(optional, default = NULL) Index (e.g. NAO index) array +from forescating of SFS1 with at least two dimensions (time , member) or +(time, statistic). The temporal dimension, by default 'time', must be equal +to 1, the forecast year target. The dimension 'member' must be greater than +1. The dimension 'statistic' must be equal to 2, for containing the two +paramenters of a normal distribution (mean and sd) representing the ensemble +of a SFS. It is not possible to have the dimension 'member' and 'statistic' +together.} -\item{index_fcst2}{(optional, default = NULL) Index (e.g. NAO index) array from forescating of SFS2 -with at least two dimensions (time , member) or (time, statistic). -The temporal dimension, by default 'time', must be equal to 1, the forecast year target. -The dimension 'member' must be greater than 1. -The dimension 'statistic' must be equal to 2, for containing the two paramenters of -a normal distribution (mean and sd) representing the ensemble of a SFS. -It is not possible to have the dimension 'member' and 'statistic' together.} +\item{index_fcst2}{(optional, default = NULL) Index (e.g. NAO index) array +from forescating of SFS2 with at least two dimensions (time , member) or +(time, statistic). The temporal dimension, by default 'time', must be equal +to 1, the forecast year target. The dimension 'member' must be greater than +1. The dimension 'statistic' must be equal to 2, for containing the two +paramenters of a normal distribution (mean and sd) representing the ensemble +of a SFS. It is not possible to have the dimension 'member' and 'statistic' +together.} \item{method_BC}{A character vector of maximun length 2 indicating the bias correction methodology to be applied on each SFS. If it is 'none' or any of -its elements is 'none', the bias correction won't be applied. -Available methods developped are "ME" (a bias correction scheme based on the -mean error or bias between observation and predictions to correct the -predicted values), and "LMEV" (a bias correction scheme based on a linear -model using ensemble variance of index as predictor). (see Sanchez-Garcia, -E. et al (2019), https://doi.org/10.5194/asr-16-165-2019 for more details).} +its elements is 'none', the bias correction won't be applied. Available +methods developped are "ME" (a bias correction scheme based on the mean +error or bias between observation and predictions to correct the predicted +values), and "LMEV" (a bias correction scheme based on a linear model using +ensemble variance of index as predictor). (see Sanchez-Garcia, E. et al +(2019), https://doi.org/10.5194/asr-16-165-2019 for more details).} \item{time_dim_name}{A character string indicating the name of the temporal dimension, by default 'time'.} @@ -69,20 +73,19 @@ dimension, by default 'time'.} \value{ BEI_PDFBest() returns an array with the parameters that caracterize the PDFs, with at least a temporal dimension, by default 'time' and dimension -'statistic' equal to 2. -The firt statistic is the parameter 'mean' of the PDF for the best estimation -combining the two SFSs PDFs. -The second statistic is the parameter 'standard deviation' of the PDF for -the best estimation combining the two SFSs PDFs. -If index_fcst1 and/or index_fcst2 are null, returns the values for hindcast period. -Otherwise, it returns the values for a forecast year. +'statistic' equal to 2. The firt statistic is the parameter 'mean' of the PDF +for the best estimation combining the two SFSs PDFs. The second statistic is +the parameter 'standard deviation' of the PDF for the best estimation +combining the two SFSs PDFs. If index_fcst1 and/or index_fcst2 are null, +returns the values for hindcast period. Otherwise, it returns the values for a +forecast year. } \description{ This function implements the computation to obtain the index Probability Density Functions (PDFs) (e.g. NAO index) obtained to combining the Index PDFs for two Seasonal Forecast Systems (SFSs), the Best Index estimation (see Sanchez-Garcia, E. et al (2019), -https://doi.org/10.5194/asr-16-165-2019 for more details about the +\url{https://doi.org/10.5194/asr-16-165-2019} for more details about the methodology applied to estimate the Best Index). } \examples{ @@ -115,7 +118,8 @@ dim(index_fcst1) <- c(time = 1, member = 8, season = 2) index_fcst2 <- rnorm(18, mean = -0.5, sd = 4) dim(index_fcst2) <- c(time = 1, member = 9, season = 2) method_BC <- c('LMEV', 'ME') -res <- BEI_PDFBest(index_obs, index_hind1, index_hind2, index_fcst1, index_fcst2, method_BC) +res <- BEI_PDFBest(index_obs, index_hind1, index_hind2, index_fcst1, + index_fcst2, method_BC) dim(res) # time statistic season # 1 2 2 @@ -123,7 +127,7 @@ dim(res) \references{ Regionally improved seasonal forecast of precipitation through Best estimation of winter NAO, Sanchez-Garcia, E. et al., -Adv. Sci. Res., 16, 165174, 2019, https://doi.org/10.5194/asr-16-165-2019 +Adv. Sci. Res., 16, 165174, 2019, \url{https://doi.org/10.5194/asr-16-165-2019} } \author{ Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} diff --git a/man/BEI_Weights.Rd b/man/BEI_Weights.Rd index 867a4eb0102a41b88f8ac64ac7707d6fb7b3b37a..9f54ac6c3e1b7c99dc18fe24b0b14a2bdb523958 100644 --- a/man/BEI_Weights.Rd +++ b/man/BEI_Weights.Rd @@ -10,15 +10,15 @@ BEI_Weights(index_weight, pdf_weight, time_dim_name = "time") \item{index_weight}{Index (e.g. NAO index) array, from a dataset of SFSs for a period of years, with at least dimensions 'member'. Additional dimensions, for instance, a temporal dimension as 'time', -must have the same lenght in both parameters, -'index_weight' and 'pdf_weight'.} +must have the same lenght in both parameters, 'index_weight' and +'pdf_weight'.} \item{pdf_weight}{Statistics array to define a Gaussian PDF with at least -dimensions 'statistic'. -The firt statistic is the parameter 'mean' of the PDF and -the second statistic is the parameter 'standard deviation' of the PDF.} +dimensions 'statistic'. The firt statistic is the parameter 'mean' of the PDF +and the second statistic is the parameter 'standard deviation' of the PDF.} -\item{time_dim_name}{A character string indicating the name of the temporal dimension, by default 'time'.} +\item{time_dim_name}{A character string indicating the name of the temporal +dimension, by default 'time'.} } \value{ BEI_Weights() returns a normalized weights array with the same @@ -45,9 +45,9 @@ dim(res) } \references{ -Regionally improved seasonal forecast of precipitation through Best -estimation of winter NAO, Sanchez-Garcia, E. et al., -Adv. Sci. Res., 16, 165174, 2019, https://doi.org/10.5194/asr-16-165-2019 +Regionally improved seasonal forecast of precipitation through +Best estimation of winter NAO, Sanchez-Garcia, E. et al., +Adv. Sci. Res., 16, 165174, 2019, \url{https://doi.org/10.5194/asr-16-165-2019} } \author{ Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} diff --git a/man/CST_AdamontAnalog.Rd b/man/CST_AdamontAnalog.Rd index 889258a19176ba267cedd7db715467678fd1390d..12e150945c129ae2dd82781d85edd80690f7bcf5 100644 --- a/man/CST_AdamontAnalog.Rd +++ b/man/CST_AdamontAnalog.Rd @@ -34,47 +34,50 @@ AdamontAnalog( } \arguments{ \item{exp}{\itemize{ -\item\code{CST_AdamontAnalog}{experiment data an object of class \code{s2dv_cube}, can be output -from quantile correction using CST_AdamontQQCorr} -\item\code{AdamontAnalog}{experiment data array with named dimension}}} +\item\code{CST_AdamontAnalog}{experiment data an object of class + \code{s2dv_cube}, can be output from quantile correction using + CST_AdamontQQCorr.} +\item\code{AdamontAnalog}{experiment data array with named dimension.}}} \item{obs}{\itemize{ \item\code{CST_AdamontAnalog}{reference data, also of class \code{s2dv_cube}.} \item\code{AdamontAnalog}{reference data array with named dimension.}} Note that lat/lon dimensions need to be the same as \code{exp}} -\item{wt_exp}{corresponding weather types (same dimensions as \code{exp$data} -but lat/lon)} +\item{wt_exp}{Corresponding weather types (same dimensions as \code{exp$data} +but lat/lon).} -\item{wt_obs}{corresponding weather types (same dimensions as \code{obs$data} +\item{wt_obs}{Corresponding weather types (same dimensions as \code{obs$data} but lat/lon)} -\item{nanalogs}{integer defining the number of analog values to return +\item{nanalogs}{Integer defining the number of analog values to return (default: 5)} -\item{method}{a character string indicating the method used for analog -definition - Coded are 'pattcorr': pattern correlation - 'rain1' (for precip patterns): rain occurrence consistency - 'rain01' (for precip patterns): rain occurrence/non - occurrence consistency} +\item{method}{A character string indicating the method used for analog +definition. Coded are: +\itemize{ + \item{'pattcorr': pattern correlation.} + \item{'rain1' (for precip patterns): rain occurrence consistency.} + \item{'rain01' (for precip patterns): rain occurrence/non occurrence + consistency} +}} -\item{thres}{real number indicating the threshold to define rain +\item{thres}{Real number indicating the threshold to define rain occurrence/non occurrence in rain(0)1} -\item{search_obsdims}{list of dimensions in \code{obs} along which analogs are -searched for} +\item{search_obsdims}{List of dimensions in \code{obs} along which analogs are +searched for.} -\item{londim}{name of longitude dimension} +\item{londim}{Name of longitude dimension.} -\item{latdim}{name of latitude dimension} +\item{latdim}{Name of latitude dimension.} } \value{ analog_vals \itemize{ -\item\code{CST_AdamontAnalog}{an object of class \code{s2dv_cube} containing nanalogs -analog values for each value of \code{exp} input data} -\item\code{AdamontAnalog}{an array containing nanalogs analog values}} + \item\code{CST_AdamontAnalog}{An object of class \code{s2dv_cube} containing + nanalogs analog values for each value of \code{exp} input data.} + \item\code{AdamontAnalog}{An array containing nanalogs analog values.}} } \description{ This function searches for analogs in a reference dataset for @@ -87,6 +90,8 @@ wt_exp <- sample(1:3, 15*6*3, replace=T) dim(wt_exp) <- c(dataset=1, member=15, sdate=6, ftime=3) wt_obs <- sample(1:3, 6*3, replace=T) dim(wt_obs) <- c(dataset=1, member=1, sdate=6, ftime=3) +analog_vals <- CST_AdamontAnalog(exp = lonlat_temp$exp, obs = lonlat_temp$obs, + wt_exp = wt_exp, wt_obs = wt_obs, nanalogs = 2) } \dontrun{ wt_exp <- sample(1:3, 15*6*3, replace=T) diff --git a/man/CST_AdamontQQCorr.Rd b/man/CST_AdamontQQCorr.Rd index eb750644b2a161b59841482a36da65077f8413eb..35ab00ade4221087c7878ddfd80eaa57e33566cc 100644 --- a/man/CST_AdamontQQCorr.Rd +++ b/man/CST_AdamontQQCorr.Rd @@ -16,32 +16,32 @@ CST_AdamontQQCorr( ) } \arguments{ -\item{exp}{experiment data an object of class \code{s2dv_cube}} +\item{exp}{Experiment data an object of class \code{s2dv_cube}.} -\item{wt_exp}{corresponding weather types (same dimensions as \code{exp$data} -but lat/lon)} +\item{wt_exp}{Corresponding weather types (same dimensions as \code{exp$data} +but lat/lon).} -\item{obs}{reference data, also of class \code{s2dv_cube}. lat/lon dimensions +\item{obs}{Reference data, also of class \code{s2dv_cube}. lat/lon dimensions can differ from \code{exp} if non rectilinear latlon grids are used, in which case regrid should be set to TRUE and .NearestNeighbors \code{NN} -output should be provided} +output should be provided.} -\item{wt_obs}{corresponding weather types (same dimensions as \code{obs} but -lat/lon)} +\item{wt_obs}{Corresponding weather types (same dimensions as \code{obs} but +lat/lon).} -\item{corrdims}{list of dimensions in \code{exp} for which quantile mapping -correction is applied} +\item{corrdims}{List of dimensions in \code{exp} for which quantile mapping +correction is applied.} -\item{londim}{character name of longitude dimension in \code{exp} and -\code{obs}} +\item{londim}{Character name of longitude dimension in \code{exp} and +\code{obs}.} -\item{latdim}{character name of latitude dimension in \code{exp} and -\code{obs}} +\item{latdim}{Character name of latitude dimension in \code{exp} and +\code{obs}.} } \value{ -an object of class \code{s2dv_cube} containing experiment data on the - lat/lon grid of \code{obs} input data, corrected by quantile mapping - depending on the weather types \code{wt_exp} +An object of class \code{s2dv_cube} containing experiment data on the +lat/lon grid of \code{obs} input data, corrected by quantile mapping +depending on the weather types \code{wt_exp}. } \description{ This function computes a quantile mapping based on weather types diff --git a/man/CST_Analogs.Rd b/man/CST_Analogs.Rd index b0242f584023df4d157937e7f92d4c972791fa9e..e085b752f5c757f9d1afa5bb8ab821fea7fa7607 100644 --- a/man/CST_Analogs.Rd +++ b/man/CST_Analogs.Rd @@ -148,7 +148,7 @@ from surface pressure using analogues. Clim. Dyn., 41, 1419-1437. \email{pascal.yiou@lsce.ipsl.fr} } \seealso{ -code{\link{CST_Load}}, \code{\link[s2dv]{Load}} and +\code{\link{CST_Load}}, \code{\link[s2dv]{Load}} and \code{\link[s2dv]{CDORemap}} } \author{ diff --git a/man/CST_AnalogsPredictors.Rd b/man/CST_AnalogsPredictors.Rd index 152b0c8a7060026f06ff1c72b04b0a9b2ae12015..c2196534ba3efdad6d88e6419f323a83a9dbf83a 100644 --- a/man/CST_AnalogsPredictors.Rd +++ b/man/CST_AnalogsPredictors.Rd @@ -25,124 +25,138 @@ CST_AnalogsPredictors( ) } \arguments{ -\item{exp}{List of arrays with downscaled period seasonal forecast data. The list -has to contain model atmospheric variables (instantaneous 12h data) that must -be indentify by parenthesis name. -For precipitation: -- u component of wind at 500 hPa (u500_mod) in m/s -- v component of wind at 500 hPa (v500_mod) in m/s -- temperature at 500 hPa (t500_mod) in K -- temperature at 850 hPa (t850_mod) in K -- specific humidity at 700 hPa (q700_mod) in g/kg +\item{exp}{List of arrays with downscaled period seasonal forecast data. The +list has to contain model atmospheric variables (instantaneous 12h data) +that must be indentify by parenthesis name. For precipitation: +\itemize{ + \item{u component of wind at 500 hPa (u500_mod) in m/s.} + \item{v component of wind at 500 hPa (v500_mod) in m/s.} + \item{temperature at 500 hPa (t500_mod) in K.} + \item{temperature at 850 hPa (t850_mod) in K.} + \item{specific humidity at 700 hPa (q700_mod) in g/kg. } +} For temperature: -- u component of wind at 500 hPa (u500_mod) in m/s -- v component of wind at 500 hPa (v500_mod) in m/s -- temperature at 500 hPa (t500_mod) in K -- temperature at 700 hPa (t700_mod) in K -- temperature at 850 hPa (t850_mod) in K -- specific humidity at 700 hPa (q700_mod) in g/kg -- 2 meters temperature (tm2m_mod) in K -The arrays must have at least three dimensions with names 'lon', 'lat' and 'time'. -(lon = gridpoints of longitude, lat = gridpoints of latitude, time = number of downscaling days) -Seasonal forecast variables must have the same resolution and -domain as reanalysis variables ('obs' parameter, below).} +\itemize{ + \item{u component of wind at 500 hPa (u500_mod) in m/s.} + \item{v component of wind at 500 hPa (v500_mod) in m/s.} + \item{temperature at 500 hPa (t500_mod) in K.} + \item{temperature at 700 hPa (t700_mod) in K. } + \item{temperature at 850 hPa (t850_mod) in K.} + \item{specific humidity at 700 hPa (q700_mod) in g/kg. } + \item{2 meters temperature (tm2m_mod) in K.} +} +The arrays must have at least three dimensions with names 'lon', 'lat' and +'time'. (lon = gridpoints of longitude, lat = gridpoints of latitude, +time = number of downscaling days) Seasonal forecast variables must have the +same resolution and domain as reanalysis variables ('obs' parameter, below).} \item{slp}{Array with atmospheric seasonal forecast model sea level pressure -(instantaneous 12h data) that must be indentify as 'slp' (hPa). It has the same -resolution as 'exp' and 'obs' paremeters but with an extended domain. -This domain contains extra degrees (most in the north and west part) compare to -synoptic domain. The array must have at least three dimensions -with names 'lon', 'lat' and 'time'.} +(instantaneous 12h data) that must be indentify as 'slp' (hPa). It has the +same resolution as 'exp' and 'obs' paremeters but with an extended domain. +This domain contains extra degrees (most in the north and west part) compare +to synoptic domain. The array must have at least three dimensions with +names 'lon', 'lat' and 'time'.} \item{obs}{List of arrays with training period reanalysis data. The list has to contain reanalysis atmospheric variables (instantaneous -12h data) that must be indentify by parenthesis name. -For precipitation: -- u component of wind at 500 hPa (u500) in m/s -- v component of wind at 500 hPa (v500) in m/s -- temperature at 500 hPa (t500) in K -- temperature at 850 hPa (t850) in K -- sea level pressure (slp) in hPa -- specific humidity at 700 hPa (q700) in g/kg +12h data) that must be indentify by parenthesis name. For precipitation: +\itemize{ + \item{u component of wind at 500 hPa (u500) in m/s.} + \item{v component of wind at 500 hPa (v500) in m/s.} + \item{temperature at 500 hPa (t500) in K.} + \item{temperature at 850 hPa (t850) in K.} + \item{sea level pressure (slp) in hPa.} + \item{specific humidity at 700 hPa (q700) in g/kg.} +} For maximum and minimum temperature: -- u component of wind at 500 hPa (u500) in m/s -- v component of wind at 500 hPa (v500) in m/s -- temperature at 500 hPa (t500) in K -- temperature at 700 hPa (t700) in K -- temperature at 850 hPa (t850) in K -- sea level pressure (slp) in hPa -- specific humidity at 700 hPa (q700) in g/kg -- 2 meters temperature (tm2m) in K -The arrays must have at least three dimensions with names 'lon', 'lat' and 'time'.} +\itemize{ + \item{u component of wind at 500 hPa (u500) in m/s.} + \item{v component of wind at 500 hPa (v500) in m/s.} + \item{temperature at 500 hPa (t500) in K.} + \item{temperature at 700 hPa (t700) in K.} + \item{temperature at 850 hPa (t850) in K.} + \item{sea level pressure (slp) in hPa.} + \item{specific humidity at 700 hPa (q700) in g/kg} + \item{2 meters temperature (tm2m) in K} +} +The arrays must have at least three dimensions with names 'lon', 'lat' and +'time'.} \item{lon}{Vector of the synoptic longitude (from (-180º) to 180º), The vector must go from west to east. The same as for the training function.} -\item{lat}{Vector of the synoptic latitude. The vector must go from north to south. -The same as for the training function.} +\item{lat}{Vector of the synoptic latitude. The vector must go from north to +south. The same as for the training function.} \item{slp_lon}{Vector of the extended longitude (from (-180º) to 180º), The vector must go from west to east. The same as for the training function.} -\item{slp_lat}{Vector of the extended latitude. The vector must go from north to south. -The same as for the training function.} +\item{slp_lat}{Vector of the extended latitude. The vector must go from north +to south. The same as for the training function.} \item{var_name}{Variable name to downscale. There are two options: 'prec' for precipitation and 'temp' for maximum and minimum temperature.} \item{hr_obs}{Local path of HR observational files (maestro and pcp/tmx-tmn). -For precipitation can be downloaded from http://www.aemet.es/documentos/es/serviciosclimaticos/cambio_climat/datos_diarios/dato_observacional/rejilla_5km/v2/Serie_AEMET_v2_pcp_1951a202006_txt.tar.gz -For maximum and minimum temperature can be downloaded from http://www.aemet.es/documentos/es/serviciosclimaticos/cambio_climat/datos_diarios/dato_observacional/rejilla_5km/temperatura/v1/tmax/Serie_AEMET_v1_tmax_1951a202006_txt.tar.gz and http://www.aemet.es/documentos/es/serviciosclimaticos/cambio_climat/datos_diarios/dato_observacional/rejilla_5km/temperatura/v1/tmin/Serie_AEMET_v1_tmin_1951a202006_txt.tar.gz respetively. -Maestro file (maestro_red_hr_SPAIN.txt) has gridpoint (nptos), longitude (lon), latitude (lat) and -altitude (alt) in columns (vector structure). -Data file (pcp/tmx/tmn_red_SPAIN_1951-201903.txt) includes 5km resolution spanish daily data -(precipitation or maximum and minimum temperature from january 1951 to june 2020. See README -file for more information. -IMPORTANT!: HR observational period must be the same as for reanalysis variables. -It is assumed that the training period is smaller than the HR original one (1951-2019), so it is -needed to make a new ascii file with the new period and the same structure as original, -specifying the training dates in the name (e.g. 'pcp_red_SPAIN_19810101-19961231.txt' for -'19810101-19961231' period).} +For precipitation and temperature can be downloaded from the following link: +\url{https://www.aemet.es/en/serviciosclimaticos/cambio_climat/datos_diarios?w=2} +respetively. Maestro file (maestro_red_hr_SPAIN.txt) has gridpoint (nptos), +longitude (lon), latitude (lat) and altitude (alt) in columns (vector +structure). Data file (pcp/tmx/tmn_red_SPAIN_1951-201903.txt) includes 5km +resolution spanish daily data (precipitation or maximum and minimum +temperature from january 1951 to june 2020. See README file for more +information. IMPORTANT!: HR observational period must be the same as for +reanalysis variables. It is assumed that the training period is smaller than +the HR original one (1951-2019), so it is needed to make a new ascii file +with the new period and the same structure as original, specifying the +training dates in the name +(e.g. 'pcp_red_SPAIN_19810101-19961231.txt' for '19810101-19961231' period).} \item{tdates}{Training period dates in format YYYYMMDD(start)-YYYYMMDD(end) (e.g. 19810101-20181231).} -\item{ddates}{Downscaling period dates in format YYYYMMDD(start)-YYYYMMDD(end) (e.g. 20191001-20200331).} +\item{ddates}{Downscaling period dates in format YYYYMMDD(start)-YYYYMMDD(end) +(e.g. 20191001-20200331).} -\item{restrain}{Output (list of matrix) obtained from 'training_analogs' function. -For precipitation, 'restrain' object must contains um, vm, nger, gu92, gv92, -gu52, gv52, neni, vdmin, vref, ccm, lab_pred and cor_pred variables. -For maximum and minimum temperature, 'restrain' object must contains um, vm, -insol, neni, vdmin y vref. See 'AnalogsPred_train.R' for more information.} +\item{restrain}{Output (list of matrix) obtained from 'training_analogs' +function. For precipitation, 'restrain' object must contains um, vm, nger, +gu92, gv92, gu52, gv52, neni, vdmin, vref, ccm, lab_pred and cor_pred +variables. For maximum and minimum temperature, 'restrain' object must +contains um, vm, insol, neni, vdmin y vref. See 'AnalogsPred_train.R' for +more information.} -\item{dim_name_longitude}{A character string indicating the name of the longitude -dimension, by default 'longitude'.} +\item{dim_name_longitude}{A character string indicating the name of the +longitude dimension, by default 'longitude'.} -\item{dim_name_latitude}{A character string indicating the name of the latitude -dimension, by default 'latitude'.} +\item{dim_name_latitude}{A character string indicating the name of the +latitude dimension, by default 'latitude'.} \item{dim_name_time}{A character string indicating the name of the time dimension, by default 'time'.} } \value{ -Matrix with seasonal forecast precipitation (mm) or -maximum and minimum temperature (dozens of ºC) in a 5km x 5km regular grid -over peninsular Spain and Balearic Islands. The resulted matrices have two -dimensions ('ddates' x 'nptos').(ddates = number of downscaling days -and nptos = number of 'hr_obs' gridpoints). +Matrix with seasonal forecast precipitation (mm) or maximum and +minimum temperature (dozens of ºC) in a 5km x 5km regular grid over peninsular +Spain and Balearic Islands. The resulted matrices have two dimensions +('ddates' x 'nptos').(ddates = number of downscaling days and nptos = number +of 'hr_obs' gridpoints). } \description{ -This function downscales low resolution precipitation data (e.g. from -Seasonal Forecast Models) through the association with an observational high -resolution (HR) dataset (AEMET 5 km gridded data of daily precipitation (Peral et al., 2017)) -and a collection of predictors and past synoptic situations similar to estimated day. -The method uses three domains: -- peninsular Spain and Balearic Islands domain (5 km resolution): HR precipitation - and the downscaling result domain. -- synoptic domain (low resolution, e.g. 1.5º x 1.5º): it should be centered over Iberian Peninsula - and cover enough extension to detect as much synoptic situations as possible. -- extended domain (low resolution, e.g. 1.5º x 1.5º): it should have the same resolution -as synoptic domain. It is used for SLP Seasonal Forecast Models. +This function downscales low resolution precipitation data (e.g. +from Seasonal Forecast Models) through the association with an observational +high resolution (HR) dataset (AEMET 5 km gridded data of daily precipitation +(Peral et al., 2017)) and a collection of predictors and past synoptic +situations similar to estimated day. The method uses three domains: +\itemize{ + \item{Peninsular Spain and Balearic Islands domain (5 km resolution): HR precipitation + and the downscaling result domain.} + \item{Synoptic domain (low resolution, e.g. 1.5º x 1.5º): it should be + centered over Iberian Peninsula and cover enough extension to detect + as much synoptic situations as possible.} + \item{Extended domain (low resolution, e.g. 1.5º x 1.5º): it should have the + same resolution as synoptic domain. It is used for SLP Seasonal + Forecast Models.} +} } \author{ Marta Dominguez Alonso - AEMET, \email{mdomingueza@aemet.es} diff --git a/man/CST_Anomaly.Rd b/man/CST_Anomaly.Rd index 3af85b5fc6ca2d742cf29bd6e0a1159f54dc088e..cbd665b3be6581c47af9df9b7b8e0c2ca9e9c74c 100644 --- a/man/CST_Anomaly.Rd +++ b/man/CST_Anomaly.Rd @@ -80,12 +80,7 @@ obs <- list(data = obs, lat = lat, lon = lon) attr(exp, 'class') <- 's2dv_cube' attr(obs, 'class') <- 's2dv_cube' -anom1 <- CST_Anomaly(exp = exp, obs = obs, cross = FALSE, memb = TRUE) -anom2 <- CST_Anomaly(exp = exp, obs = obs, cross = TRUE, memb = TRUE) -anom3 <- CST_Anomaly(exp = exp, obs = obs, cross = TRUE, memb = FALSE) -anom4 <- CST_Anomaly(exp = exp, obs = obs, cross = FALSE, memb = FALSE) -anom5 <- CST_Anomaly(lonlat_temp$exp) -anom6 <- CST_Anomaly(obs = lonlat_temp$obs) +anom <- CST_Anomaly(exp = exp, obs = obs, cross = FALSE, memb = TRUE) } \seealso{ diff --git a/man/CST_BEI_Weighting.Rd b/man/CST_BEI_Weighting.Rd index d6f65bb52123d014377037e435f5c33893756b9f..89fb4f6e3862c8b3d953e6b65f3bb2c6624a36b6 100644 --- a/man/CST_BEI_Weighting.Rd +++ b/man/CST_BEI_Weighting.Rd @@ -36,13 +36,12 @@ or four dimensions depending if the variable is spatially aggregated variable (as e.g. precipitation or temperature), dimension (time, tercile, lat, lon), containing the terciles probabilities computing with weighted members. The first tercil is the lower tercile, the second is the normal tercile and -the third is the upper tercile. -If 'type' = 'ensembleMean', the function returns, in the element data from -'var_exp' parameter, an array with at least one or three dimensions -depending if the variable is a spatially aggregated variable -(as e.g. NAO index)(time) or it is spatial variable (as e.g. precipitation -or temperature) (time, lat, lon), containing the ensemble means computing -with weighted members.} +the third is the upper tercile. If 'type' = 'ensembleMean', the function +returns, in the element data from 'var_exp' parameter, an array with at +least one or three dimensions depending if the variable is a spatially +aggregated variable (as e.g. NAO index)(time) or it is spatial variable (as +e.g. precipitation or temperature) (time, lat, lon), containing the ensemble +means computing with weighted members.} \item{time_dim_name}{A character string indicating the name of the temporal dimension, by default 'time'.} @@ -64,7 +63,8 @@ Systems (SFSs). \examples{ var_exp <- 1 : (2 * 4 * 3 * 2) dim(var_exp) <- c(time = 2, member = 4, lat = 3, lon = 2) -aweights <- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3, 0.1, 0.2, 0.4, 0.4, 0.1, 0.2, 0.4, 0.2) +aweights <- c(0.2, 0.1, 0.3, 0.4, 0.1, 0.2, 0.4, 0.3, 0.1, 0.2, 0.4, 0.4, 0.1, + 0.2, 0.4, 0.2) dim(aweights) <- c(time = 2, member = 4, dataset = 2) var_exp <- list(data = var_exp) class(var_exp) <- 's2dv_cube' @@ -76,7 +76,7 @@ dim(res_CST$data) \references{ Regionally improved seasonal forecast of precipitation through Best estimation of winter NAO, Sanchez-Garcia, E. et al., -Adv. Sci. Res., 16, 165174, 2019, https://doi.org/10.5194/asr-16-165-2019 +Adv. Sci. Res., 16, 165174, 2019, \url{https://doi.org/10.5194/asr-16-165-2019} } \author{ Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} diff --git a/man/CST_Calibration.Rd b/man/CST_Calibration.Rd index 73cac8ab543a701708cab5c0f2d5b936152043a4..5d79ae41a34bc994c0bbe69560a9c5e61ddb6cc6 100644 --- a/man/CST_Calibration.Rd +++ b/man/CST_Calibration.Rd @@ -21,37 +21,74 @@ CST_Calibration( ) } \arguments{ -\item{exp}{an object of class \code{s2dv_cube} as returned by \code{CST_Load} function, containing the seasonal hindcast experiment data in the element named \code{$data}. The hindcast is used to calibrate the forecast in case the forecast is provided; if not, the same hindcast will be calibrated instead.} +\item{exp}{An object of class \code{s2dv_cube} as returned by \code{CST_Load} +function, containing the seasonal hindcast experiment data in the element +named \code{$data}. The hindcast is used to calibrate the forecast in case +the forecast is provided; if not, the same hindcast will be calibrated +instead.} -\item{obs}{an object of class \code{s2dv_cube} as returned by \code{CST_Load} function, containing the observed data in the element named \code{$data}.} +\item{obs}{An object of class \code{s2dv_cube} as returned by \code{CST_Load} +function, containing the observed data in the element named \code{$data}.} -\item{exp_cor}{an optional object of class \code{s2dv_cube} as returned by \code{CST_Load} function, containing the seasonal forecast experiment data in the element named \code{$data}. If the forecast is provided, it will be calibrated using the hindcast and observations; if not, the hindcast will be calibrated instead.} +\item{exp_cor}{An optional object of class \code{s2dv_cube} as returned by +\code{CST_Load} function, containing the seasonal forecast experiment data +in the element named \code{$data}. If the forecast is provided, it will be +calibrated using the hindcast and observations; if not, the hindcast will be +calibrated instead.} -\item{cal.method}{is the calibration method used, can be either \code{bias}, \code{evmos}, \code{mse_min}, \code{crps_min} or \code{rpc-based}. Default value is \code{mse_min}.} +\item{cal.method}{Is the calibration method used, can be either \code{bias}, +\code{evmos}, \code{mse_min}, \code{crps_min} or \code{rpc-based}. Default +value is \code{mse_min}.} -\item{eval.method}{is the sampling method used, can be either \code{in-sample} or \code{leave-one-out}. Default value is the \code{leave-one-out} cross validation. In case the forecast is provided, any chosen eval.method is over-ruled and a third option is used.} +\item{eval.method}{Is the sampling method used, can be either \code{in-sample} +or \code{leave-one-out}. Default value is the \code{leave-one-out} cross +validation. In case the forecast is provided, any chosen eval.method is +over-ruled and a third option is used.} -\item{multi.model}{is a boolean that is used only for the \code{mse_min} method. If multi-model ensembles or ensembles of different sizes are used, it must be set to \code{TRUE}. By default it is \code{FALSE}. Differences between the two approaches are generally small but may become large when using small ensemble sizes. Using multi.model when the calibration method is \code{bias}, \code{evmos} or \code{crps_min} will not affect the result.} +\item{multi.model}{Is a boolean that is used only for the \code{mse_min} +method. If multi-model ensembles or ensembles of different sizes are used, +it must be set to \code{TRUE}. By default it is \code{FALSE}. Differences +between the two approaches are generally small but may become large when +using small ensemble sizes. Using multi.model when the calibration method is +\code{bias}, \code{evmos} or \code{crps_min} will not affect the result.} -\item{na.fill}{is a boolean that indicates what happens in case calibration is not possible or will yield unreliable results. This happens when three or less forecasts-observation pairs are available to perform the training phase of the calibration. By default \code{na.fill} is set to true such that NA values will be returned. If \code{na.fill} is set to false, the uncorrected data will be returned.} +\item{na.fill}{Is a boolean that indicates what happens in case calibration is +not possible or will yield unreliable results. This happens when three or +less forecasts-observation pairs are available to perform the training phase +of the calibration. By default \code{na.fill} is set to true such that NA +values will be returned. If \code{na.fill} is set to false, the uncorrected +data will be returned.} -\item{na.rm}{is a boolean that indicates whether to remove the NA values or not. The default value is \code{TRUE}. See Details section for further information about its use and compatibility with \code{na.fill}.} +\item{na.rm}{Is a boolean that indicates whether to remove the NA values or +not. The default value is \code{TRUE}. See Details section for further +information about its use and compatibility with \code{na.fill}.} -\item{apply_to}{is a character string that indicates whether to apply the calibration to all the forecast (\code{"all"}) or only to those where the correlation between the ensemble mean and the observations is statistically significant (\code{"sign"}). Only useful if \code{cal.method == "rpc-based"}.} +\item{apply_to}{Is a character string that indicates whether to apply the +calibration to all the forecast (\code{"all"}) or only to those where the +correlation between the ensemble mean and the observations is statistically +significant (\code{"sign"}). Only useful if \code{cal.method == "rpc-based"}.} -\item{alpha}{is a numeric value indicating the significance level for the correlation test. Only useful if \code{cal.method == "rpc-based" & apply_to == "sign"}.} +\item{alpha}{Is a numeric value indicating the significance level for the +correlation test. Only useful if \code{cal.method == "rpc-based" & +apply_to == "sign"}.} -\item{memb_dim}{is a character string indicating the name of the member dimension. By default, it is set to 'member'.} +\item{memb_dim}{Is a character string indicating the name of the member +dimension. By default, it is set to 'member'.} -\item{sdate_dim}{is a character string indicating the name of the start date dimension. By default, it is set to 'sdate'.} +\item{sdate_dim}{Is a character string indicating the name of the start date +dimension. By default, it is set to 'sdate'.} -\item{ncores}{is an integer that indicates the number of cores for parallel computations using multiApply function. The default value is one.} +\item{ncores}{Is an integer that indicates the number of cores for parallel +computations using multiApply function. The default value is one.} } \value{ -an object of class \code{s2dv_cube} containing the calibrated forecasts in the element \code{$data} with the same dimensions as the one in the exp object. +An object of class \code{s2dv_cube} containing the calibrated +forecasts in the element \code{$data} with the same dimensions as the one in +the exp object. } \description{ -Equivalent to function \code{Calibration} but for objects of class \code{s2dv_cube}. +Equivalent to function \code{Calibration} but for objects of +class \code{s2dv_cube}. } \examples{ # Example 1: @@ -65,7 +102,8 @@ exp <- list(data = mod1, lat = lat, lon = lon) obs <- list(data = obs1, lat = lat, lon = lon) attr(exp, 'class') <- 's2dv_cube' attr(obs, 'class') <- 's2dv_cube' -a <- CST_Calibration(exp = exp, obs = obs, cal.method = "mse_min", eval.method = "in-sample") +a <- CST_Calibration(exp = exp, obs = obs, cal.method = "mse_min", + eval.method = "in-sample") str(a) # Example 2: @@ -83,7 +121,8 @@ exp_cor <- list(data = mod2, lat = lat, lon = lon) attr(exp, 'class') <- 's2dv_cube' attr(obs, 'class') <- 's2dv_cube' attr(exp_cor, 'class') <- 's2dv_cube' -a <- CST_Calibration(exp = exp, obs = obs, exp_cor = exp_cor, cal.method = "evmos") +a <- CST_Calibration(exp = exp, obs = obs, exp_cor = exp_cor, + cal.method = "evmos") str(a) } \seealso{ diff --git a/man/CST_CategoricalEnsCombination.Rd b/man/CST_CategoricalEnsCombination.Rd index c23f8341c201921984cdebb6bf05a43997042752..9ef28f43b6e9ffc09a1f163ee8d0ca70ac712be1 100644 --- a/man/CST_CategoricalEnsCombination.Rd +++ b/man/CST_CategoricalEnsCombination.Rd @@ -2,7 +2,8 @@ % Please edit documentation in R/CST_CategoricalEnsCombination.R \name{CST_CategoricalEnsCombination} \alias{CST_CategoricalEnsCombination} -\title{Make categorical forecast based on a multi-model forecast with potential for calibrate} +\title{Make categorical forecast based on a multi-model forecast with potential for +calibrate} \usage{ CST_CategoricalEnsCombination( exp, @@ -14,87 +15,105 @@ CST_CategoricalEnsCombination( ) } \arguments{ -\item{exp}{an object of class \code{s2dv_cube} as returned by \code{CST_Load} function, containing the seasonal forecast experiment data in the element named \code{$data}. The amount of forecasting models is equal to the size of the \code{dataset} dimension of the data array. The amount of members per model may be different. The size of the \code{member} dimension of the data array is equal to the maximum of the ensemble members among the models. Models with smaller ensemble sizes have residual indices of \code{member} dimension in the data array filled with NA values.} +\item{exp}{An object of class \code{s2dv_cube} as returned by \code{CST_Load} +function, containing the seasonal forecast experiment data in the element +named \code{$data}. The amount of forecasting models is equal to the size of +the \code{dataset} dimension of the data array. The amount of members per +model may be different. The size of the \code{member} dimension of the data +array is equal to the maximum of the ensemble members among the models. +Models with smaller ensemble sizes have residual indices of \code{member} +dimension in the data array filled with NA values.} -\item{obs}{an object of class \code{s2dv_cube} as returned by \code{CST_Load} function, containing the observed data in the element named \code{$data}.} +\item{obs}{An object of class \code{s2dv_cube} as returned by \code{CST_Load} +function, containing the observed data in the element named \code{$data}.} -\item{cat.method}{method used to produce the categorical forecast, can be either \code{pool}, \code{comb}, \code{mmw} or \code{obs}. The method pool assumes equal weight for all ensemble members while the method comb assumes equal weight for each model. The weighting method is descirbed in Rajagopalan et al. (2002), Robertson et al. (2004) and Van Schaeybroeck and Vannitsem (2019). Finally, the \code{obs} method classifies the observations into the different categories and therefore contains only 0 and 1 values.} +\item{cat.method}{Method used to produce the categorical forecast, can be +either \code{pool}, \code{comb}, \code{mmw} or \code{obs}. The method pool +assumes equal weight for all ensemble members while the method comb assumes +equal weight for each model. The weighting method is descirbed in +Rajagopalan et al. (2002), Robertson et al. (2004) and Van Schaeybroeck and +Vannitsem (2019). Finally, the \code{obs} method classifies the observations +into the different categories and therefore contains only 0 and 1 values.} -\item{eval.method}{is the sampling method used, can be either \code{"in-sample"} or \code{"leave-one-out"}. Default value is the \code{"leave-one-out"} cross validation.} +\item{eval.method}{Is the sampling method used, can be either +\code{"in-sample"} or \code{"leave-one-out"}. Default value is the +\code{"leave-one-out"} cross validation.} -\item{amt.cat}{is the amount of categories. Equally-sized quantiles will be calculated based on the amount of categories.} +\item{amt.cat}{Is the amount of categories. Equally-sized quantiles will be +calculated based on the amount of categories.} \item{...}{other parameters to be passed on to the calibration procedure.} } \value{ -an object of class \code{s2dv_cube} containing the categorical forecasts in the element called \code{$data}. The first two dimensions of the returned object are named dataset and member and are both of size one. An additional dimension named category is introduced and is of size amt.cat. +An object of class \code{s2dv_cube} containing the categorical +forecasts in the element called \code{$data}. The first two dimensions of the +returned object are named dataset and member and are both of size one. An +additional dimension named category is introduced and is of size amt.cat. } \description{ -This function converts a multi-model ensemble forecast -into a categorical forecast by giving the probability -for each category. Different methods are available to combine -the different ensemble forecasting models into -probabilistic categorical forecasts. +This function converts a multi-model ensemble forecast into a +categorical forecast by giving the probability for each category. Different +methods are available to combine the different ensemble forecasting models +into probabilistic categorical forecasts. -Motivation: -Beyond the short range, the unpredictable component of weather -predictions becomes substantial due to the chaotic nature of the earth -system. Therefore, predictions can mostly be skillful when used in a probabilistic sense. -In practice this is done using ensemble forecasts. It is then common to -convert the ensemble forecasts to occurence probabilities for different categories. -These categories typically are taken as terciles from climatolgical distributions. -For instance for temperature, there is a cold, normal and warm class. -Commonly multiple ensemble forecasting systems -are available but some models may be more competitive than others -for the variable, region and user need under consideration. Therefore, -when calculating the category probabilities, the ensemble members of -the different forecasting system may be differently weighted. -Such weighting is typically done by comparison of the ensemble forecasts -with observations. +Motivation: Beyond the short range, the unpredictable component of weather +predictions becomes substantial due to the chaotic nature of the earth system. +Therefore, predictions can mostly be skillful when used in a probabilistic +sense. In practice this is done using ensemble forecasts. It is then common to +convert the ensemble forecasts to occurence probabilities for different +categories. These categories typically are taken as terciles from +climatolgical distributions. For instance for temperature, there is a cold, +normal and warm class. Commonly multiple ensemble forecasting systems are +available but some models may be more competitive than others for the +variable, region and user need under consideration. Therefore, when +calculating the category probabilities, the ensemble members of the different +forecasting system may be differently weighted. Such weighting is typically +done by comparison of the ensemble forecasts with observations. -Description of the tool: -The tool considers all forecasts (all members from all forecasting systems) -and converts them into occurrence probabilities of different categories. -The amount of categories can be changed and are taken as the -climatological quantiles (e.g. terciles), extracted -from the observational data. -The methods that are available to combine the ensemble forecasting models into -probabilistic categorical forecasts are: 1) ensemble pooling where +Description of the tool: The tool considers all forecasts (all members from +all forecasting systems) and converts them into occurrence probabilities of +different categories. The amount of categories can be changed and are taken as +the climatological quantiles (e.g. terciles), extracted from the observational +data. The methods that are available to combine the ensemble forecasting +models into probabilistic categorical forecasts are: 1) ensemble pooling where all ensemble members of all ensemble systems are weighted equally, 2) model combination where each model system is weighted equally, and, 3) model weighting. The model weighting method is described in Rajagopalan et al. (2002), -Robertson et al. 2004 and Van Schaeybroeck and Vannitsem (2019). -More specifically, this method uses different weights for the -occurence probability predicted by the available models and by a climatological model -and optimizes the weights by minimizing the ignorance score. -Finally, the function can also be used to categorize the observations -in the categorical quantiles. +Robertson et al. 2004 and Van Schaeybroeck and Vannitsem (2019). More +specifically, this method uses different weights for the occurence probability +predicted by the available models and by a climatological model and optimizes +the weights by minimizing the ignorance score. Finally, the function can also +be used to categorize the observations in the categorical quantiles. } \examples{ -mod1 <- 1 : (2 * 3 * 4 * 5 * 6 * 7) -dim(mod1) <- c(dataset = 2, member = 3, sdate = 4, ftime = 5, lat = 6, lon = 7) -mod1[ 2, 3, , , , ] <- NA +mod1 <- 1 : (2 * 2* 4 * 5 * 2 * 2) +dim(mod1) <- c(dataset = 2, member = 2, sdate = 4, ftime = 5, lat = 2, lon = 2) +mod1[2, 1, , , , ] <- NA dimnames(mod1)[[1]] <- c("MF", "UKMO") -obs1 <- 1 : (1 * 1 * 4 * 5 * 6 * 7) -dim(obs1) <- c(dataset = 1, member = 1, sdate = 4, ftime = 5, lat = 6, lon = 7) +obs1 <- 1 : (1 * 1 * 4 * 5 * 2 * 2) +dim(obs1) <- c(dataset = 1, member = 1, sdate = 4, ftime = 5, lat = 2, lon = 2) lon <- seq(0, 30, 5) lat <- seq(0, 25, 5) exp <- list(data = mod1, lat = lat, lon = lon) obs <- list(data = obs1, lat = lat, lon = lon) attr(exp, 'class') <- 's2dv_cube' attr(obs, 'class') <- 's2dv_cube' -\donttest{ a <- CST_CategoricalEnsCombination(exp = exp, obs = obs, amt.cat = 3, cat.method = "mmw") -} + } \references{ -Rajagopalan, B., Lall, U., & Zebiak, S. E. (2002). Categorical climate forecasts through regularization and optimal combination of multiple GCM ensembles. Monthly Weather Review, 130(7), 1792-1811. +Rajagopalan, B., Lall, U., & Zebiak, S. E. (2002). Categorical +climate forecasts through regularization and optimal combination of multiple +GCM ensembles. Monthly Weather Review, 130(7), 1792-1811. -Robertson, A. W., Lall, U., Zebiak, S. E., & Goddard, L. (2004). Improved combination of multiple atmospheric GCM ensembles for seasonal prediction. Monthly Weather Review, 132(12), 2732-2744. +Robertson, A. W., Lall, U., Zebiak, S. E., & Goddard, L. (2004). +Improved combination of multiple atmospheric GCM ensembles for seasonal +prediction. Monthly Weather Review, 132(12), 2732-2744. -Van Schaeybroeck, B., & Vannitsem, S. (2019). Postprocessing of Long-Range Forecasts. In Statistical Postprocessing of Ensemble Forecasts (pp. 267-290). +Van Schaeybroeck, B., & Vannitsem, S. (2019). Postprocessing of +Long-Range Forecasts. In Statistical Postprocessing of Ensemble Forecasts (pp. 267-290). } \author{ Bert Van Schaeybroeck, \email{bertvs@meteo.be} diff --git a/man/CST_DynBiasCorrection.Rd b/man/CST_DynBiasCorrection.Rd index e2467e72bbc98eee7b45c0b5bd6192506bf22fcf..f9eb3c9ec67329d1215c98ddafa2aa27d434d89b 100644 --- a/man/CST_DynBiasCorrection.Rd +++ b/man/CST_DynBiasCorrection.Rd @@ -16,29 +16,29 @@ CST_DynBiasCorrection( ) } \arguments{ -\item{exp}{an s2v_cube object with the experiment data} +\item{exp}{An s2v_cube object with the experiment data.} -\item{obs}{an s2dv_cube object with the reference data} +\item{obs}{An s2dv_cube object with the reference data.} -\item{method}{a character string indicating the method to apply bias -correction among these ones: "PTF","RQUANT","QUANT","SSPLIN"} +\item{method}{A character string indicating the method to apply bias +correction among these ones: "PTF","RQUANT","QUANT","SSPLIN".} -\item{wetday}{logical indicating whether to perform wet day correction +\item{wetday}{Logical indicating whether to perform wet day correction or not OR a numeric threshold below which all values are set to zero (by default is set to 'FALSE').} -\item{proxy}{a character string indicating the proxy for local dimension +\item{proxy}{A character string indicating the proxy for local dimension 'dim' or inverse of persistence 'theta' to apply the dynamical conditioned bias correction method.} -\item{quanti}{a number lower than 1 indicating the quantile to perform -the computation of local dimension and theta} +\item{quanti}{A number lower than 1 indicating the quantile to perform +the computation of local dimension and theta.} -\item{ncores}{The number of cores to use in parallel computation} +\item{ncores}{The number of cores to use in parallel computation.} } \value{ -dynbias an s2dvcube object with a bias correction performed -conditioned by local dimension 'dim' or inverse of persistence 'theta' +dynbias An s2dvcube object with a bias correction performed +conditioned by local dimension 'dim' or inverse of persistence 'theta'. } \description{ This function perform a bias correction conditioned by the @@ -81,7 +81,7 @@ dynbias2 <- CST_DynBiasCorrection(exp = expL, obs = obsL, proxy= "dim", Faranda, D., Alvarez-Castro, M.C., Messori, G., Rodriguez, D., and Yiou, P. (2019). The hammam effect or how a warm ocean enhances large scale atmospheric predictability.Nature Communications, 10(1), 1316. -DOI = https://doi.org/10.1038/s41467-019-09305-8 " +DOI = \url{https://doi.org/10.1038/s41467-019-09305-8} " Faranda, D., Gabriele Messori and Pascal Yiou. (2017). Dynamical proxies of North Atlantic predictability and extremes. diff --git a/man/CST_EnsClustering.Rd b/man/CST_EnsClustering.Rd index 83f5e7a1a1b17c3217044ffaecc09ccb383fd3de..28a094fff6cfb2993593f713d8da1b8a4c316fb2 100644 --- a/man/CST_EnsClustering.Rd +++ b/man/CST_EnsClustering.Rd @@ -19,112 +19,102 @@ CST_EnsClustering( ) } \arguments{ -\item{exp}{An object of the class 's2dv_cube', containing the variables to be analysed. -Each data object in the list is expected to have an element named \code{$data} with at least two -spatial dimensions named "lon" and "lat", and dimensions "dataset", "member", "ftime", "sdate".} +\item{exp}{An object of the class 's2dv_cube', containing the variables to be +analysed. Each data object in the list is expected to have an element named +\code{$data} with at least two spatial dimensions named "lon" and "lat", and +dimensions "dataset", "member", "ftime", "sdate".} -\item{time_moment}{Decides the moment to be applied to the time dimension. Can be either 'mean' (time mean), -'sd' (standard deviation along time) or 'perc' (a selected percentile on time). -If 'perc' the keyword 'time_percentile' is also used.} +\item{time_moment}{Decides the moment to be applied to the time dimension. Can +be either 'mean' (time mean), 'sd' (standard deviation along time) or 'perc' +(a selected percentile on time). If 'perc' the keyword 'time_percentile' is +also used.} -\item{numclus}{Number of clusters (scenarios) to be calculated. -If set to NULL the number of ensemble members divided by 10 is used, with a minimum of 2 and a maximum of 8.} +\item{numclus}{Number of clusters (scenarios) to be calculated. If set to NULL +the number of ensemble members divided by 10 is used, with a minimum of 2 +and a maximum of 8.} \item{lon_lim}{List with the two longitude margins in `c(-180,180)` format.} \item{lat_lim}{List with the two latitude margins.} -\item{variance_explained}{variance (percentage) to be explained by the set of EOFs. -Defaults to 80. Not used if numpcs is specified.} +\item{variance_explained}{variance (percentage) to be explained by the set of +EOFs. Defaults to 80. Not used if numpcs is specified.} \item{numpcs}{Number of EOFs retained in the analysis (optional).} -\item{time_dim}{String or character array with name(s) of dimension(s) over which to compute statistics. -If omitted c("ftime", "sdate", "time") are searched in this order.} +\item{time_dim}{String or character array with name(s) of dimension(s) over +which to compute statistics. If omitted c("ftime", "sdate", "time") are +searched in this order.} -\item{time_percentile}{Set the percentile in time you want to analyse (used for `time_moment = "perc").} +\item{time_percentile}{Set the percentile in time you want to analyse (used +for `time_moment = "perc").} -\item{cluster_dim}{Dimension along which to cluster. Typically "member" or "sdate". -This can also be a list like c("member", "sdate").} +\item{cluster_dim}{Dimension along which to cluster. Typically "member" or +"sdate". This can also be a list like c("member", "sdate").} \item{verbose}{Logical for verbose output} } \value{ -A list with elements \code{$cluster} (cluster assigned for each member), - \code{$freq} (relative frequency of each cluster), \code{$closest_member} - (representative member for each cluster), \code{$repr_field} (list of fields - for each representative member), \code{composites} (list of mean fields for each cluster), - \code{$lon} (selected longitudes of output fields), - \code{$lat} (selected longitudes of output fields). +A list with elements \code{$cluster} (cluster assigned for each +member), \code{$freq} (relative frequency of each cluster), +\code{$closest_member} (representative member for each cluster), +\code{$repr_field} (list of fields for each representative member), +\code{composites} (list of mean fields for each cluster), \code{$lon} +(selected longitudes of output fields), \code{$lat} (selected longitudes of +output fields). } \description{ This function performs a clustering on members/starting dates -and returns a number of scenarios, with representative members for each of them. -The clustering is performed in a reduced EOF space. +and returns a number of scenarios, with representative members for each of +them. The clustering is performed in a reduced EOF space. Motivation: Ensemble forecasts give a probabilistic insight of average weather conditions on extended timescales, i.e. from sub-seasonal to seasonal and beyond. With large ensembles, it is often an advantage to be able to group members -according to similar characteristics and to select the most representative member for each cluster. -This can be useful to characterize the most probable forecast scenarios in a multi-model -(or single model) ensemble prediction. This approach, applied at a regional level, -can also be used to identify the subset of ensemble members that best represent the -full range of possible solutions for downscaling applications. -The choice of the ensemble members is made flexible in order to meet the requirements -of specific (regional) climate information products, to be tailored for different regions and user needs. +according to similar characteristics and to select the most representative +member for each cluster. This can be useful to characterize the most probable +forecast scenarios in a multi-model (or single model) ensemble prediction. +This approach, applied at a regional level, can also be used to identify the +subset of ensemble members that best represent the full range of possible +solutions for downscaling applications. The choice of the ensemble members is +made flexible in order to meet the requirements of specific (regional) climate +information products, to be tailored for different regions and user needs. Description of the tool: -EnsClustering is a cluster analysis tool, based on the k-means algorithm, for ensemble predictions. -The aim is to group ensemble members according to similar characteristics and -to select the most representative member for each cluster. -The user chooses which feature of the data is used to group the ensemble members by clustering: -time mean, maximum, a certain percentile (e.g., 75% as in the examples below), -standard deviation and trend over the time period. For each ensemble member this value -is computed at each grid point, obtaining N lat-lon maps, where N is the number of ensemble members. -The anomaly is computed subtracting the ensemble mean of these maps to each of the single maps. -The anomaly is therefore computed with respect to the ensemble members (and not with respect to the time) -and the Empirical Orthogonal Function (EOF) analysis is applied to these anomaly maps. -Regarding the EOF analysis, the user can choose either how many Principal Components (PCs) -to retain or the percentage of explained variance to keep. After reducing dimensionality via -EOF analysis, k-means analysis is applied using the desired subset of PCs. - -The major final outputs are the classification in clusters, i.e. which member belongs -to which cluster (in k-means analysis the number k of clusters needs to be defined -prior to the analysis) and the most representative member for each cluster, -which is the closest member to the cluster centroid. -Other outputs refer to the statistics of clustering: in the PC space, the minimum and -the maximum distance between a member in a cluster and the cluster centroid -(i.e. the closest and the furthest member), the intra-cluster standard -deviation for each cluster (i.e. how much the cluster is compact). +EnsClustering is a cluster analysis tool, based on the k-means algorithm, for +ensemble predictions. The aim is to group ensemble members according to +similar characteristics and to select the most representative member for each +cluster. The user chooses which feature of the data is used to group the +ensemble members by clustering: time mean, maximum, a certain percentile +(e.g., 75% as in the examples below), standard deviation and trend over the +time period. For each ensemble member this value is computed at each grid +point, obtaining N lat-lon maps, where N is the number of ensemble members. +The anomaly is computed subtracting the ensemble mean of these maps to each of +the single maps. The anomaly is therefore computed with respect to the +ensemble members (and not with respect to the time) and the Empirical +Orthogonal Function (EOF) analysis is applied to these anomaly maps. Regarding +the EOF analysis, the user can choose either how many Principal Components +(PCs) to retain or the percentage of explained variance to keep. After +reducing dimensionality via EOF analysis, k-means analysis is applied using +the desired subset of PCs. + +The major final outputs are the classification in clusters, i.e. which member +belongs to which cluster (in k-means analysis the number k of clusters needs +to be defined prior to the analysis) and the most representative member for +each cluster, which is the closest member to the cluster centroid. Other +outputs refer to the statistics of clustering: in the PC space, the minimum +and the maximum distance between a member in a cluster and the cluster +centroid (i.e. the closest and the furthest member), the intra-cluster +standard deviation for each cluster (i.e. how much the cluster is compact). } \examples{ -\donttest{ exp <- lonlat_temp$exp +exp$data <- ClimProjDiags::Subset(exp$data, along = c('member', 'lat'), list(1:2, 1:7)) +exp$lat <- exp$lat[1:7] # Example 1: Cluster on all start dates, members and models res <- CST_EnsClustering(exp, numclus = 3, - cluster_dim = c("member", "dataset", "sdate")) -iclus <- res$cluster[2, 1, 3] - -#print(paste("Cluster of 2. member, 1. dataset, 3. sdate:", iclus)) -#print(paste("Frequency (numerosity) of cluster (", iclus, ") :", res$freq[iclus])) -s2dv::PlotEquiMap(res$repr_field[iclus, , ], exp$lon, exp$lat, - filled.continents = FALSE, - toptitle = paste("Representative field of cluster", iclus)) - -# Example 2: Cluster on members retaining 4 EOFs during -# preliminary dimensional reduction -res <- CST_EnsClustering(exp, numclus = 3, numpcs = 4, cluster_dim = "member") - -# Example 3: Cluster on members, retain 80\% of variance during -# preliminary dimensional reduction -res <- CST_EnsClustering(exp, numclus = 3, variance_explained = 80, - cluster_dim = "member") - -# Example 4: Compute percentile in time -res <- CST_EnsClustering(exp, numclus = 3, time_percentile = 90, - time_moment = "perc", cluster_dim = "member") -} + cluster_dim = c("sdate")) } \author{ diff --git a/man/CST_MergeDims.Rd b/man/CST_MergeDims.Rd index 0762e83f9567f082040a8692ebf18c2c90ca45fd..aaa04ba52d3d08cad71335c87b8f193484dc1251 100644 --- a/man/CST_MergeDims.Rd +++ b/man/CST_MergeDims.Rd @@ -12,19 +12,24 @@ CST_MergeDims( ) } \arguments{ -\item{data}{a 's2dv_cube' object} +\item{data}{An 's2dv_cube' object} -\item{merge_dims}{a character vector indicating the names of the dimensions to merge} +\item{merge_dims}{A character vector indicating the names of the dimensions to +merge.} -\item{rename_dim}{a character string indicating the name of the output dimension. If left at NULL, the first dimension name provided in parameter \code{merge_dims} will be used.} +\item{rename_dim}{a character string indicating the name of the output +dimension. If left at NULL, the first dimension name provided in parameter +\code{merge_dims} will be used.} -\item{na.rm}{a logical indicating if the NA values should be removed or not.} +\item{na.rm}{A logical indicating if the NA values should be removed or not.} } \description{ -This function merges two dimensions of the array \code{data} in a 's2dv_cube' object into one. The user can select the dimensions to merge and provide the final name of the dimension. The user can select to remove NA values or keep them. +This function merges two dimensions of the array \code{data} in a +'s2dv_cube' object into one. The user can select the dimensions to merge and +provide the final name of the dimension. The user can select to remove NA +values or keep them. } \examples{ - data <- 1 : c(2 * 3 * 4 * 5 * 6 * 7) dim(data) <- c(time = 7, lat = 2, lon = 3, monthly = 4, member = 6, dataset = 5, var = 1) diff --git a/man/CST_MultiEOF.Rd b/man/CST_MultiEOF.Rd index 0621112e7932655715184c63d67aa4b038716475..dcafcc414e3e42ac7ca70b56bf06903efd99bacf 100644 --- a/man/CST_MultiEOF.Rd +++ b/man/CST_MultiEOF.Rd @@ -14,61 +14,52 @@ CST_MultiEOF( ) } \arguments{ -\item{datalist}{A list of objects of the class 's2dv_cube', containing the variables to be analysed. -Each data object in the list is expected to have an element named \code{$data} with at least two -spatial dimensions named "lon" and "lat", a dimension "ftime" and a dimension "sdate".} +\item{datalist}{A list of objects of the class 's2dv_cube', containing the +variables to be analysed. Each data object in the list is expected to have +an element named \code{$data} with at least two spatial dimensions named +"lon" and "lat", a dimension "ftime" and a dimension "sdate".} -\item{neof_max}{Maximum number of single eofs considered in the first decomposition} +\item{neof_max}{Maximum number of single eofs considered in the first +decomposition.} -\item{neof_composed}{Number of composed eofs to return in output} +\item{neof_composed}{Number of composed eofs to return in output.} -\item{minvar}{Minimum variance fraction to be explained in first decomposition} +\item{minvar}{Minimum variance fraction to be explained in first decomposition.} -\item{lon_lim}{Vector with longitudinal range limits for the EOF calculation for all input variables} +\item{lon_lim}{Vector with longitudinal range limits for the EOF calculation +for all input variables.} -\item{lat_lim}{Vector with latitudinal range limits for the EOF calculation for all input variables} +\item{lat_lim}{Vector with latitudinal range limits for the EOF calculation +for all input variables.} } \value{ -A list with elements \code{$coeff} (an array of time-varying principal component coefficients), - \code{$variance} (a matrix of explained variances), - \code{eof_pattern} (a matrix of EOF patterns obtained by regression for each variable). +A list with elements \code{$coeff} (an array of time-varying principal +component coefficients), \code{$variance} (a matrix of explained variances), +\code{eof_pattern} (a matrix of EOF patterns obtained by regression for each +variable). } \description{ This function performs EOF analysis over multiple variables, -accepting in input a list of CSTools objects. Based on Singular Value Decomposition. For each field the EOFs are computed and the corresponding PCs are standardized (unit variance, zero mean); the minimum number of principal components needed to reach the user-defined variance is retained. The function weights the input data for the latitude cosine square root. +accepting in input a list of CSTools objects. Based on Singular Value +Decomposition. For each field the EOFs are computed and the corresponding PCs +are standardized (unit variance, zero mean); the minimum number of principal +components needed to reach the user-defined variance is retained. The function +weights the input data for the latitude cosine square root. } \examples{ -\donttest{ -library(zeallot) -library(ClimProjDiags) -c(exp, obs) \%<-\% lonlat_temp +exp <- lonlat_temp$exp +exp$data <- ClimProjDiags::Subset(exp$data, along = c('lat', 'lon'), list(1:4, 1:4)) +exp$lat <- exp$lat[1:4] +exp$lon <- exp$lon[1:4] + # Create three datasets (from the members) exp1 <- exp exp2 <- exp -exp3 <- exp -exp1$data <- Subset(exp$data, along = 2, indices = 1 : 5) -exp2$data <- Subset(exp$data, along = 2, indices = 6 : 10) -exp3$data <- Subset(exp$data, along = 2, indices = 11 : 15) - -cal <- CST_MultiEOF(list(exp1, exp2, exp3), neof_max=5, neof_composed=2) -str(cal) -# List of 3 -# $ coeff : num [1:3, 1:6, 1:2, 1:5] -0.312 -0.588 0.724 1.202 1.181 ... -# $ variance : num [1:2, 1:5] 0.413 0.239 0.352 0.27 0.389 ... -# $ eof_pattern: num [1:3, 1:53, 1:22, 1:2, 1:5] -1.47 -0.446 -0.656 -1.534 -0.464 ... -dim(cal$coeff) -# ftime sdate eof member -# 3 6 2 3 -cal <- CST_MultiEOF(list(exp1, exp2, exp3) , minvar=0.9) -str(cal) -# $ coeff : num [1:3, 1:6, 1:5, 1:5] 0.338 0.603 -0.736 -1.191 -1.198 ... -# $ variance : num [1:5, 1:5] 0.3903 0.2264 0.1861 0.1032 0.0379 ... -# $ eof_pattern: num [1:3, 1:53, 1:22, 1:5, 1:5] 1.477 0.454 0.651 1.541 0.47 ... +exp1$data <- ClimProjDiags::Subset(exp$data, along = 2, indices = 1:5) +exp2$data <- ClimProjDiags::Subset(exp$data, along = 2, indices = 6:10) -cal <- CST_MultiEOF(list(exp1, exp2)) -cal <- CST_MultiEOF(list(exp1, exp2, exp3), lon_lim=c(5, 30), lat_lim=c(35, 50), neof_composed=3) -} +cal <- CST_MultiEOF(list(exp1, exp2) , minvar = 0.9) } \author{ Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} diff --git a/man/CST_MultiMetric.Rd b/man/CST_MultiMetric.Rd index 5590ab893945db323d703490692be975c704ceed..f348aab2022d120005594b8fff5c8583018d13ff 100644 --- a/man/CST_MultiMetric.Rd +++ b/man/CST_MultiMetric.Rd @@ -15,55 +15,66 @@ CST_MultiMetric( ) } \arguments{ -\item{exp}{an object of class \code{s2dv_cube} as returned by \code{CST_Anomaly} function, containing the anomaly of the seasonal forecast experiments data in the element named \code{$data}.} +\item{exp}{An object of class \code{s2dv_cube} as returned by +\code{CST_Anomaly} function, containing the anomaly of the seasonal forecast +experiments data in the element named \code{$data}.} -\item{obs}{an object of class \code{s2dv_cube} as returned by \code{CST_Anomaly} function, containing the anomaly of observed data in the element named \code{$data}.} +\item{obs}{An object of class \code{s2dv_cube} as returned by +\code{CST_Anomaly} function, containing the anomaly of observed data in the +element named \code{$data}.} -\item{metric}{a character string giving the metric for computing the maximum skill. This must be one of the strings 'correlation', 'rms', 'rmsss' and 'rpss'. If 'rpss' is chossen the terciles probabilities are evaluated.} +\item{metric}{A character string giving the metric for computing the maximum +skill. This must be one of the strings 'correlation', 'rms', 'rmsss' and +'rpss'. If 'rpss' is chossen the terciles probabilities are evaluated.} -\item{multimodel}{a logical value indicating whether a Multi-Model Mean should be computed.} +\item{multimodel}{A logical value indicating whether a Multi-Model Mean should +be computed.} -\item{time_dim}{name of the temporal dimension where a mean will be applied. It can be NULL, the default value is 'ftime'.} +\item{time_dim}{Name of the temporal dimension where a mean will be applied. +It can be NULL, the default value is 'ftime'.} -\item{memb_dim}{name of the member dimension. It can be NULL, the default value is 'member'.} +\item{memb_dim}{Name of the member dimension. It can be NULL, the default +value is 'member'.} -\item{sdate_dim}{name of the start date dimension or a dimension name identifiying the different forecast. It can be NULL, the default value is 'sdate'.} +\item{sdate_dim}{Name of the start date dimension or a dimension name +identifiying the different forecast. It can be NULL, the default value is +'sdate'.} } \value{ -an object of class \code{s2dv_cube} containing the statistics of the selected metric in the element \code{$data} which is a list of arrays: for the metric requested and others for statistics about its signeificance. The arrays have two dataset dimensions equal to the 'dataset' dimension in the \code{exp$data} and \code{obs$data} inputs. If \code{multimodel} is TRUE, the first position in the first 'nexp' dimension correspons to the Multi-Model Mean. +An object of class \code{s2dv_cube} containing the statistics of the +selected metric in the element \code{$data} which is a list of arrays: for the +metric requested and others for statistics about its signeificance. The arrays +have two dataset dimensions equal to the 'dataset' dimension in the +\code{exp$data} and \code{obs$data} inputs. If \code{multimodel} is TRUE, the +first position in the first 'nexp' dimension correspons to the Multi-Model Mean. } \description{ -This function calculates correlation (Anomaly Correlation Coefficient; ACC), root mean square error (RMS) and the root mean square error skill score (RMSSS) of individual anomaly models and multi-models mean (if desired) with the observations. +This function calculates correlation (Anomaly Correlation +Coefficient; ACC), root mean square error (RMS) and the root mean square error +skill score (RMSSS) of individual anomaly models and multi-models mean (if +desired) with the observations. } \examples{ -library(zeallot) -mod <- 1 : (2 * 3 * 4 * 5 * 6 * 7) -dim(mod) <- c(dataset = 2, member = 3, sdate = 4, ftime = 5, lat = 6, lon = 7) -obs <- 1 : (1 * 1 * 4 * 5 * 6 * 7) -dim(obs) <- c(dataset = 1, member = 1, sdate = 4, ftime = 5, lat = 6, lon = 7) +mod <- rnorm(2 * 2 * 4 * 5 * 2 * 2) +dim(mod) <- c(dataset = 2, member = 2, sdate = 4, ftime = 5, lat = 2, lon = 2) +obs <- rnorm(1 * 1 * 4 * 5 * 2 * 2) +dim(obs) <- c(dataset = 1, member = 1, sdate = 4, ftime = 5, lat = 2, lon = 2) lon <- seq(0, 30, 5) lat <- seq(0, 25, 5) exp <- list(data = mod, lat = lat, lon = lon) obs <- list(data = obs, lat = lat, lon = lon) attr(exp, 'class') <- 's2dv_cube' attr(obs, 'class') <- 's2dv_cube' -c(ano_exp, ano_obs) \%<-\% CST_Anomaly(exp = exp, obs = obs, cross = TRUE, memb = TRUE) -a <- CST_MultiMetric(exp = ano_exp, obs = ano_obs) -str(a) -\donttest{ -exp <- lonlat_temp$exp -obs <- lonlat_temp$obs -a <- CST_MultiMetric(exp, obs, metric = 'rpss', multimodel = FALSE) -a <- CST_MultiMetric(exp, obs, metric = 'correlation') -a <- CST_MultiMetric(exp, obs, metric = 'rms') -a <- CST_MultiMetric(exp, obs, metric = 'rmsss') -} +a <- CST_MultiMetric(exp = exp, obs = obs) } \references{ -Mishra, N., Prodhomme, C., & Guemas, V. (n.d.). Multi-Model Skill Assessment of Seasonal Temperature and Precipitation Forecasts over Europe, 29-31.\url{https://link.springer.com/article/10.1007/s00382-018-4404-z} +Mishra, N., Prodhomme, C., & Guemas, V. (n.d.). Multi-Model Skill +Assessment of Seasonal Temperature and Precipitation Forecasts over Europe, +29-31.\url{https://link.springer.com/article/10.1007/s00382-018-4404-z} } \seealso{ -\code{\link[s2dv]{Corr}}, \code{\link[s2dv]{RMS}}, \code{\link[s2dv]{RMSSS}} and \code{\link{CST_Load}} +\code{\link[s2dv]{Corr}}, \code{\link[s2dv]{RMS}}, +\code{\link[s2dv]{RMSSS}} and \code{\link{CST_Load}} } \author{ Mishra Niti, \email{niti.mishra@bsc.es} diff --git a/man/CST_MultivarRMSE.Rd b/man/CST_MultivarRMSE.Rd index 577c08dbd8290241d3da8606d418bf6b835ca75d..e6de57a4677803444131ccb17e2d1dae2f2833af 100644 --- a/man/CST_MultivarRMSE.Rd +++ b/man/CST_MultivarRMSE.Rd @@ -7,17 +7,30 @@ CST_MultivarRMSE(exp, obs, weight = NULL) } \arguments{ -\item{exp}{a list of objects, one for each variable, of class \code{s2dv_cube} as returned by \code{CST_Anomaly} function, containing the anomaly of the seasonal forecast experiment data in the element named \code{$data}.} +\item{exp}{A list of objects, one for each variable, of class \code{s2dv_cube} +as returned by \code{CST_Anomaly} function, containing the anomaly of the +seasonal forecast experiment data in the element named \code{$data}.} -\item{obs}{a list of objects, one for each variable (in the same order than the input in 'exp') of class \code{s2dv_cube} as returned by \code{CST_Anomaly} function, containing the observed anomaly data in the element named \code{$data}.} +\item{obs}{A list of objects, one for each variable (in the same order than +the input in 'exp') of class \code{s2dv_cube} as returned by +\code{CST_Anomaly} function, containing the observed anomaly data in the +element named \code{$data}.} -\item{weight}{(optional) a vector of weight values to assign to each variable. If no weights are defined, a value of 1 is assigned to every variable.} +\item{weight}{(optional) A vector of weight values to assign to each variable. +If no weights are defined, a value of 1 is assigned to every variable.} } \value{ -an object of class \code{s2dv_cube} containing the RMSE in the element \code{$data} which is an array with two datset dimensions equal to the 'dataset' dimension in the \code{exp$data} and \code{obs$data} inputs. An array with dimensions: c(number of exp, number of obs, 1 (the multivariate RMSE value), number of lat, number of lon) +An object of class \code{s2dv_cube} containing the RMSE in the element + \code{$data} which is an array with two datset dimensions equal to the + 'dataset' dimension in the \code{exp$data} and \code{obs$data} inputs. An + array with dimensions: c(number of exp, number of obs, 1 (the multivariate + RMSE value), number of lat, number of lon) } \description{ -This function calculates the RMSE from multiple variables, as the mean of each variable's RMSE scaled by its observed standard deviation. Variables can be weighted based on their relative importance (defined by the user). +This function calculates the RMSE from multiple variables, as the +mean of each variable's RMSE scaled by its observed standard deviation. +Variables can be weighted based on their relative importance (defined by the +user). } \examples{ # Creation of sample s2dv objects. These are not complete s2dv objects diff --git a/man/CST_ProxiesAttractor.Rd b/man/CST_ProxiesAttractor.Rd index ddf7df27e9431f104d0e127756b462729eee996e..ed21b11f4c34ff19982a8615792252be92f4cf78 100644 --- a/man/CST_ProxiesAttractor.Rd +++ b/man/CST_ProxiesAttractor.Rd @@ -7,12 +7,13 @@ CST_ProxiesAttractor(data, quanti, ncores = NULL) } \arguments{ -\item{data}{a s2dv_cube object with the data to create the attractor. Must be a matrix with the timesteps in nrow -and the grids in ncol(dat(time,grids)} +\item{data}{An s2dv_cube object with the data to create the attractor. Must be +a matrix with the timesteps in nrow and the grids in ncol(dat(time,grids)} -\item{quanti}{a number lower than 1 indicating the quantile to perform the computation of local dimension and theta} +\item{quanti}{A number lower than 1 indicating the quantile to perform the +computation of local dimension and theta.} -\item{ncores}{The number of cores to use in parallel computation} +\item{ncores}{The number of cores to use in parallel computation.} } \value{ dim and theta @@ -21,20 +22,26 @@ dim and theta This function computes two dinamical proxies of the attractor: The local dimension (d) and the inverse of the persistence (theta) for an 's2dv_cube' object. -These two parameters will be used as a condition for the computation of dynamical -scores to measure predictability and to compute bias correction conditioned by -the dynamics with the function DynBiasCorrection -Funtion based on the matlab code (davide.faranda@lsce.ipsl.fr) used in +These two parameters will be used as a condition for the computation of +dynamical scores to measure predictability and to compute bias correction +conditioned by the dynamics with the function DynBiasCorrection Function +based on the matlab code (davide.faranda@lsce.ipsl.fr) used in } \examples{ # Example 1: Computing the attractor using simple s2dv data -attractor <- CST_ProxiesAttractor(data = lonlat_temp$obs, quanti = 0.6) +obs <- rnorm(2 * 3 * 4 * 8 * 8) +dim(obs) <- c(dataset = 1, member = 2, sdate = 3, ftime = 4, lat = 8, lon = 8) +lon <- seq(10, 13.5, 0.5) +lat <- seq(40, 43.5, 0.5) +data <- list(data = obs, lon = lon, lat = lat) +class(data) <- "s2dv_cube" +attractor <- CST_ProxiesAttractor(data = data, quanti = 0.6) } \references{ Faranda, D., Alvarez-Castro, M.C., Messori, G., Rodriguez, D., and Yiou, P. (2019). The hammam effect or how a warm ocean enhances large scale atmospheric predictability. -Nature Communications, 10(1), 1316. DOI = https://doi.org/10.1038/s41467-019-09305-8 " +Nature Communications, 10(1), 1316. DOI = \url{https://doi.org/10.1038/s41467-019-09305-8} " Faranda, D., Gabriele Messori and Pascal Yiou. (2017). Dynamical proxies of North Atlantic predictability and extremes. diff --git a/man/CST_QuantileMapping.Rd b/man/CST_QuantileMapping.Rd index 71b32da9f87dbca3d93f1c6b33736bb42ccd2a7a..3c0deac4b8c2925a3270ed7352533a520735e554 100644 --- a/man/CST_QuantileMapping.Rd +++ b/man/CST_QuantileMapping.Rd @@ -37,9 +37,9 @@ ensemble members are stored in the experimental arrays. 'member' by default.} samples have been stored. It can be NULL (default) in case all samples are used.} -\item{method}{A character string indicating the method to be used:'PTF', -'DIST','RQUANT','QUANT','SSPLIN'. By default, the empirical quantile mapping -'QUANT' is used.} +\item{method}{A character string indicating the method to be used:'PTF', +'DIST', 'RQUANT', 'QUANT', 'SSPLIN'. By default, the empirical quantile +mapping 'QUANT' is used.} \item{na.rm}{A logical value indicating if missing values should be removed (FALSE by default).} @@ -67,14 +67,13 @@ exp$data <- 1 : c(1 * 3 * 5 * 4 * 3 * 2) dim(exp$data) <- c(dataset = 1, member = 3, sdate = 5, ftime = 4, lat = 3, lon = 2) class(exp) <- 's2dv_cube' +obs <- NULL obs$data <- 101 : c(100 + 1 * 1 * 5 * 4 * 3 * 2) dim(obs$data) <- c(dataset = 1, member = 1, sdate = 5, ftime = 4, lat = 3, lon = 2) class(obs) <- 's2dv_cube' res <- CST_QuantileMapping(exp, obs) -# Use data in package -\donttest{ exp <- lonlat_temp$exp exp$data <- exp$data[, , 1:4, , 1:2, 1:3] dim(exp$data) <- c(dataset = 1, member = 15, sdate = 4, ftime = 3, @@ -88,7 +87,6 @@ exp_cor$data <- exp_cor$data[, 1, 5:6, , 1:2, 1:3] dim(exp_cor$data) <- c(dataset = 1, member = 1, sdate = 2, ftime = 3, lat = 2, lon = 3) res <- CST_QuantileMapping(exp, obs, exp_cor, window_dim = 'ftime') -} } \seealso{ diff --git a/man/CST_RFSlope.Rd b/man/CST_RFSlope.Rd index b76ac93ef98a9ee157a71a664ab86a24824c84c3..ab30d81eaa577b174360e0b06447a554abcbbdda 100644 --- a/man/CST_RFSlope.Rd +++ b/man/CST_RFSlope.Rd @@ -7,29 +7,35 @@ CST_RFSlope(data, kmin = 1, time_dim = NULL, ncores = 1) } \arguments{ -\item{data}{An object of the class 's2dv_cube', containing the spatial precipitation fields to downscale. -The data object is expected to have an element named \code{$data} with at least two -spatial dimensions named "lon" and "lat" and one or more dimensions over which -to average these slopes, which can be specified by parameter \code{time_dim}.} +\item{data}{An object of the class 's2dv_cube', containing the spatial +precipitation fields to downscale. The data object is expected to have an +element named \code{$data} with at least two spatial dimensions named "lon" +and "lat" and one or more dimensions over which to average these slopes, +which can be specified by parameter \code{time_dim}.} \item{kmin}{First wavenumber for spectral slope (default \code{kmin=1}).} -\item{time_dim}{String or character array with name(s) of dimension(s) (e.g. "ftime", "sdate", "member" ...) -over which to compute spectral slopes. If a character array of dimension names is provided, the spectral slopes -will be computed as an average over all elements belonging to those dimensions. -If omitted one of c("ftime", "sdate", "time") is searched and the first one with more than one element is chosen.} +\item{time_dim}{String or character array with name(s) of dimension(s) (e.g. +"ftime", "sdate", "member" ...) over which to compute spectral slopes. If a +character array of dimension names is provided, the spectral slopes will be +computed as an average over all elements belonging to those dimensions. If +omitted one of c("ftime", "sdate", "time") is searched and the first one +with more than one element is chosen.} -\item{ncores}{is an integer that indicates the number of cores for parallel computations using multiApply function. The default value is one.} +\item{ncores}{Is an integer that indicates the number of cores for parallel +computations using multiApply function. The default value is one.} } \value{ CST_RFSlope() returns spectral slopes using the RainFARM convention -(the logarithmic slope of k*|A(k)|^2 where A(k) are the spectral amplitudes). -The returned array has the same dimensions as the \code{exp} element of the input object, -minus the dimensions specified by \code{lon_dim}, \code{lat_dim} and \code{time_dim}. + (the logarithmic slope of k*|A(k)|^2 where A(k) are the spectral amplitudes). + The returned array has the same dimensions as the \code{exp} element of the + input object, minus the dimensions specified by \code{lon_dim}, + \code{lat_dim} and \code{time_dim}. } \description{ -This function computes spatial spectral slopes from a CSTools object -to be used for RainFARM stochastic precipitation downscaling method and accepts a CSTools object (of the class 's2dv_cube') as input. +This function computes spatial spectral slopes from a CSTools +object to be used for RainFARM stochastic precipitation downscaling method and +accepts a CSTools object (of the class 's2dv_cube') as input. } \examples{ #Example using CST_RFSlope for a CSTools object diff --git a/man/CST_RFTemp.Rd b/man/CST_RFTemp.Rd index 8ab5b6f329b63174cab568199ee4e5245b8927e5..19a3c0185787b46a3319e7c5949713f35092e70a 100644 --- a/man/CST_RFTemp.Rd +++ b/man/CST_RFTemp.Rd @@ -23,52 +23,53 @@ CST_RFTemp( } \arguments{ \item{data}{An object of the class 's2dv_cube' as returned by `CST_Load`, -containing the temperature fields to downscale. -The data object is expected to have an element named \code{$data} -with at least two spatial dimensions named "lon" and "lat". -(these default names can be changed with the \code{lon_dim} and -\code{lat_dim} parameters)} +containing the temperature fields to downscale. The data object is expected +to have an element named \code{$data} with at least two spatial dimensions +named "lon" and "lat". (these default names can be changed with the +\code{lon_dim} and \code{lat_dim} parameters).} \item{oro}{An object of the class 's2dv_cube' as returned by `CST_Load`, -containing fine scale orography (in meters). -The destination downscaling area must be contained in the orography field.} +containing fine scale orography (in meters). The destination downscaling +area must be contained in the orography field.} -\item{xlim}{vector with longitude bounds for downscaling; -the full input field is downscaled if `xlim` and `ylim` are not specified.} +\item{xlim}{Vector with longitude bounds for downscaling; the full input +field is downscaled if `xlim` and `ylim` are not specified.} -\item{ylim}{vector with latitude bounds for downscaling} +\item{ylim}{Vector with latitude bounds for downscaling} -\item{lapse}{float with environmental lapse rate} +\item{lapse}{Float with environmental lapse rate} -\item{lon_dim}{string with name of longitude dimension} +\item{lon_dim}{String with name of longitude dimension} -\item{lat_dim}{string with name of latitude dimension} +\item{lat_dim}{String with name of latitude dimension} -\item{time_dim}{a vector of character string indicating the name of temporal dimension. By default, it is set to NULL and it considers "ftime", "sdate" and "time" as temporal dimensions.} +\item{time_dim}{A vector of character string indicating the name of temporal +dimension. By default, it is set to NULL and it considers "ftime", "sdate" +and "time" as temporal dimensions.} -\item{nolapse}{logical, if true `oro` is interpreted as a fine-scale -climatology and used directly for bias correction} +\item{nolapse}{Logical, if true `oro` is interpreted as a fine-scale +climatology and used directly for bias correction.} -\item{verbose}{logical if to print diagnostic output} +\item{verbose}{Logical if to print diagnostic output.} -\item{compute_delta}{logical if true returns only a delta to be used for +\item{compute_delta}{Logical if true returns only a delta to be used for out-of-sample forecasts. Returns an object of the class 's2dv_cube', containing a delta. Activates `nolapse = TRUE`.} -\item{method}{string indicating the method used for interpolation: +\item{method}{String indicating the method used for interpolation: "nearest" (nearest neighbours followed by smoothing with a circular uniform weights kernel), "bilinear" (bilinear interpolation) The two methods provide similar results, but nearest is slightly better provided that the fine-scale grid is correctly centered as a subdivision -of the large-scale grid} +of the large-scale grid.} \item{delta}{An object of the class 's2dv_cube', containing a delta to be applied to the downscaled input data. Activates `nolapse = TRUE`. The grid of this object must coincide with that of the required output.} } \value{ -CST_RFTemp() returns a downscaled CSTools object -(i.e., of the class 's2dv_cube'). +CST_RFTemp() returns a downscaled CSTools object (i.e., of the class +'s2dv_cube'). } \description{ This function implements a simple lapse rate correction of a @@ -96,11 +97,11 @@ res <- CST_RFTemp(exp, oro, xlim=c(4,8), ylim=c(43, 46), lapse=6.5) } \references{ Method described in ERA4CS MEDSCOPE milestone M3.2: -High-quality climate prediction data available to WP4 -[https://www.medscope-project.eu/the-project/deliverables-reports/]([https://www.medscope-project.eu/the-project/deliverables-reports/) +High-quality climate prediction data available to WP4 here: +\url{https://www.medscope-project.eu/the-project/deliverables-reports/} and in H2020 ECOPOTENTIAL Deliverable No. 8.1: -High resolution (1-10 km) climate, land use and ocean change scenarios -[https://www.ecopotential-project.eu/images/ecopotential/documents/D8.1.pdf](https://www.ecopotential-project.eu/images/ecopotential/documents/D8.1.pdf) +High resolution (1-10 km) climate, land use and ocean change scenarios available +here: \url{https://www.ecopotential-project.eu/images/ecopotential/documents/D8.1.pdf} } \author{ Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} diff --git a/man/CST_RFWeights.Rd b/man/CST_RFWeights.Rd index acae8c6a512d775a3f0b0e892f4c121d12f907e0..3b8e9fa7b83f78565e40763015a6431c6d1561ea 100644 --- a/man/CST_RFWeights.Rd +++ b/man/CST_RFWeights.Rd @@ -17,40 +17,49 @@ CST_RFWeights( ) } \arguments{ -\item{climfile}{Filename of a fine-scale precipitation climatology. -The file is expected to be in NetCDF format and should contain -at least one precipitation field. If several fields at different times are provided, -a climatology is derived by time averaging. -Suitable climatology files could be for example a fine-scale precipitation climatology -from a high-resolution regional climate model (see e.g. Terzago et al. 2018), a local -high-resolution gridded climatology from observations, or a reconstruction such as those which -can be downloaded from the WORLDCLIM (http://www.worldclim.org) or CHELSA (http://chelsa-climate.org) -websites. The latter data will need to be converted to NetCDF format before being used (see for example the GDAL tools (https://www.gdal.org). -It could also be a 's2dv_cube' object.} +\item{climfile}{Filename of a fine-scale precipitation climatology. The file +is expected to be in NetCDF format and should contain at least one +precipitation field. If several fields at different times are provided, +a climatology is derived by time averaging. Suitable climatology files could +be for example a fine-scale precipitation climatology from a high-resolution +regional climate model (see e.g. Terzago et al. 2018), a local +high-resolution gridded climatology from observations, or a reconstruction +such as those which can be downloaded from the WORLDCLIM +(\url{http://www.worldclim.org}) or CHELSA (\url{http://chelsa-climate.org}) +websites. The latter data will need to be converted to NetCDF format before +being used (see for example the GDAL tools (\url{https://www.gdal.org}). It +could also be an 's2dv_cube' object.} -\item{nf}{Refinement factor for downscaling (the output resolution is increased by this factor).} +\item{nf}{Refinement factor for downscaling (the output resolution is +increased by this factor).} \item{lon}{Vector of longitudes.} -\item{lat}{Vector of latitudes. -The number of longitudes and latitudes is expected to be even and the same. If not -the function will perform a subsetting to ensure this condition.} +\item{lat}{Vector of latitudes. The number of longitudes and latitudes is +expected to be even and the same. If not the function will perform a +subsetting to ensure this condition.} \item{varname}{Name of the variable to be read from \code{climfile}.} -\item{fsmooth}{Logical to use smooth conservation (default) or large-scale box-average conservation.} +\item{fsmooth}{Logical to use smooth conservation (default) or large-scale +box-average conservation.} -\item{lonname}{a character string indicating the name of the longitudinal dimension set as 'lon' by default.} +\item{lonname}{A character string indicating the name of the longitudinal +dimension set as 'lon' by default.} -\item{latname}{a character string indicating the name of the latitudinal dimension set as 'lat' by default.} +\item{latname}{A character string indicating the name of the latitudinal +dimension set as 'lat' by default.} -\item{ncores}{an integer that indicates the number of cores for parallel computations using multiApply function. The default value is one.} +\item{ncores}{An integer that indicates the number of cores for parallel +computations using multiApply function. The default value is one.} } \value{ -An object of class 's2dv_cube' containing in matrix \code{data} the weights with dimensions (lon, lat). +An object of class 's2dv_cube' containing in matrix \code{data} the +weights with dimensions (lon, lat). } \description{ -Compute climatological ("orographic") weights from a fine-scale precipitation climatology file. +Compute climatological ("orographic") weights from a fine-scale +precipitation climatology file. } \examples{ # Create weights to be used with the CST_RainFARM() or RainFARM() functions @@ -69,7 +78,7 @@ Terzago, S., Palazzi, E., & von Hardenberg, J. (2018). Stochastic downscaling of precipitation in complex orography: A simple method to reproduce a realistic fine-scale climatology. Natural Hazards and Earth System Sciences, 18(11), -2825-2840. http://doi.org/10.5194/nhess-18-2825-2018 . +2825-2840. \url{http://doi.org/10.5194/nhess-18-2825-2018} . } \author{ Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} diff --git a/man/CST_RainFARM.Rd b/man/CST_RainFARM.Rd index f86ab89cb65487fd36c22bd40e6ccddcf6cfc289..18c474276f2bc1ef41db6e124f0571f068a5479b 100644 --- a/man/CST_RainFARM.Rd +++ b/man/CST_RainFARM.Rd @@ -22,59 +22,67 @@ CST_RainFARM( \arguments{ \item{data}{An object of the class 's2dv_cube' as returned by `CST_Load`, containing the spatial precipitation fields to downscale. -The data object is expected to have an element named \code{$data} with at least two -spatial dimensions named "lon" and "lat" and one or more dimensions over which -to compute average spectral slopes (unless specified with parameter \code{slope}), -which can be specified by parameter \code{time_dim}. -The number of longitudes and latitudes in the input data is expected to be even and the same. If not -the function will perform a subsetting to ensure this condition.} +The data object is expected to have an element named \code{$data} with at +least two spatial dimensions named "lon" and "lat" and one or more +dimensions over which to compute average spectral slopes (unless specified +with parameter \code{slope}), which can be specified by parameter +\code{time_dim}. The number of longitudes and latitudes in the input data is +expected to be even and the same. If not the function will perform a +subsetting to ensure this condition.} \item{weights}{Matrix with climatological weights which can be obtained using -the \code{CST_RFWeights} function. If \code{weights=1.} (default) no weights are used. -The names of these dimensions must be at least 'lon' and 'lat'.} +the \code{CST_RFWeights} function. If \code{weights=1.} (default) no weights +are used. The names of these dimensions must be at least 'lon' and 'lat'.} \item{slope}{Prescribed spectral slope. The default is \code{slope=0.} -meaning that the slope is determined automatically over the dimensions specified by \code{time_dim}. A 1D array with named dimension can be provided (see details and examples)} +meaning that the slope is determined automatically over the dimensions +specified by \code{time_dim}. A 1D array with named dimension can be +provided (see details and examples).} -\item{nf}{Refinement factor for downscaling (the output resolution is increased by this factor).} +\item{nf}{Refinement factor for downscaling (the output resolution is +increased by this factor).} \item{kmin}{First wavenumber for spectral slope (default: \code{kmin=1}).} \item{nens}{Number of ensemble members to produce (default: \code{nens=1}).} -\item{fglob}{Logical to conserve global precipitation over the domain (default: FALSE).} +\item{fglob}{Logical to conserve global precipitation over the domain +(default: FALSE).} -\item{fsmooth}{Logical to conserve precipitation with a smoothing kernel (default: TRUE).} +\item{fsmooth}{Logical to conserve precipitation with a smoothing kernel +(default: TRUE).} -\item{nprocs}{The number of parallel processes to spawn for the use for parallel computation in multiple cores. (default: 1)} +\item{nprocs}{The number of parallel processes to spawn for the use for +parallel computation in multiple cores. (default: 1)} \item{time_dim}{String or character array with name(s) of dimension(s) (e.g. "ftime", "sdate", "member" ...) over which to compute spectral slopes. If a character array of dimension names is provided, the spectral slopes -will be computed as an average over all elements belonging to those dimensions. -If omitted one of c("ftime", "sdate", "time") is searched and the first one with more -than one element is chosen.} +will be computed as an average over all elements belonging to those +dimensions. If omitted one of c("ftime", "sdate", "time") is searched and +the first one with more than one element is chosen.} \item{verbose}{Logical for verbose output (default: FALSE).} -\item{drop_realization_dim}{Logical to remove the "realization" stochastic ensemble dimension, -needed for saving data through function CST_SaveData (default: FALSE) -with the following behaviour if set to TRUE: - -1) if \code{nens==1}: the dimension is dropped; - -2) if \code{nens>1} and a "member" dimension exists: - the "realization" and "member" dimensions are compacted (multiplied) and the resulting dimension is named "member"; - -3) if \code{nens>1} and a "member" dimension does not exist: the "realization" dimension is renamed to "member".} +\item{drop_realization_dim}{Logical to remove the "realization" stochastic +ensemble dimension, needed for saving data through function CST_SaveData +(default: FALSE) with the following behaviour if set to TRUE: +\enumerate{ + \item{if \code{nens==1}: the dimension is dropped;} + \item{if \code{nens>1} and a "member" dimension exists: the "realization" + and "member" dimensions are compacted (multiplied) and the resulting + dimension is named "member";} + \item{if \code{nens>1} and a "member" dimension does not exist: the + "realization" dimension is renamed to "member".} +}} } \value{ CST_RainFARM() returns a downscaled CSTools object (i.e., of the -class 's2dv_cube'). -If \code{nens>1} an additional dimension named "realizatio"n is added to the -\code{$data} array after the "member" dimension (unless -\code{drop_realization_dim=TRUE} is specified). -The ordering of the remaining dimensions in the \code{$data} element of the input object is maintained. +class 's2dv_cube'). If \code{nens>1} an additional dimension named +"realization" is added to the \code{$data} array after the "member" dimension +(unless \code{drop_realization_dim=TRUE} is specified). The ordering of the +remaining dimensions in the \code{$data} element of the input object is +maintained. } \description{ This function implements the RainFARM stochastic precipitation @@ -84,10 +92,13 @@ Adapted for climate downscaling and including orographic correction as described in Terzago et al. 2018. } \details{ -Wether parameter 'slope' and 'weights' presents seasonality dependency, a dimension name should match between these parameters and the input data in parameter 'data'. See example 2 below where weights and slope vary with 'sdate' dimension. +Wether parameter 'slope' and 'weights' presents seasonality +dependency, a dimension name should match between these parameters and the +input data in parameter 'data'. See example 2 below where weights and slope +vary with 'sdate' dimension. } \examples{ -#Example 1: using CST_RainFARM for a CSTools object +# Example 1: using CST_RainFARM for a CSTools object nf <- 8 # Choose a downscaling by factor 8 exp <- 1 : (2 * 3 * 4 * 8 * 8) dim(exp) <- c(dataset = 1, member = 2, sdate = 3, ftime = 4, lat = 8, lon = 8) @@ -98,26 +109,13 @@ dim(lat) <- c(lat = length(lat)) data <- list(data = exp, lon = lon, lat = lat) # Create a test array of weights ww <- array(1., dim = c(lon = 8 * nf, lat = 8 * nf)) -res <- CST_RainFARM(data, nf = nf, weights = ww, nens=3) -str(res) -#List of 3 -# $ data: num [1, 1:2, 1:3, 1:3, 1:4, 1:64, 1:64] 260 553 281 278 143 ... -# $ lon : num [1:64] 9.78 9.84 9.91 9.97 10.03 ... -# $ lat : num [1:64] 39.8 39.8 39.9 40 40 ... -dim(res$data) -# dataset member realization sdate ftime lat lon -# 1 2 3 3 4 64 64 - -# Example 2: -slo <- array(c(0.1, 0.5, 0.7), c(sdate= 3)) -wei <- array(rnorm(8 * 8 * 3), c(lon = 8, lat = 8, sdate = 3)) -res <- CST_RainFARM(lonlat_prec, - weights = wei, slope = slo, nf = 2) +res <- CST_RainFARM(data, nf = nf, weights = ww, nens = 3) } \references{ Terzago, S. et al. (2018). NHESS 18(11), 2825-2840. -http://doi.org/10.5194/nhess-18-2825-2018 ; -D'Onofrio et al. (2014), J of Hydrometeorology 15, 830-843; Rebora et. al. (2006), JHM 7, 724. +\url{http://doi.org/10.5194/nhess-18-2825-2018} ; +D'Onofrio et al. (2014), J of Hydrometeorology 15, 830-843; Rebora et. al. +(2006), JHM 7, 724. } \author{ Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} diff --git a/man/CST_RegimesAssign.Rd b/man/CST_RegimesAssign.Rd index 82d06e0b03a18d55d768505b3aa3debfb317cc56..123799b16cdd4b4c04b37617c6a2a127d76eba47 100644 --- a/man/CST_RegimesAssign.Rd +++ b/man/CST_RegimesAssign.Rd @@ -15,43 +15,58 @@ CST_RegimesAssign( ) } \arguments{ -\item{data}{a 's2dv_cube' object.} +\item{data}{An 's2dv_cube' object.} -\item{ref_maps}{a 's2dv_cube' object as the output of CST_WeatherRegimes.} +\item{ref_maps}{An 's2dv_cube' object as the output of CST_WeatherRegimes.} -\item{method}{whether the matching will be performed in terms of minimum distance (default = 'distance') or -the maximum spatial correlation (method = 'ACC') between the maps.} +\item{method}{Whether the matching will be performed in terms of minimum +distance (default = 'distance') or the maximum spatial correlation +(method = 'ACC') between the maps.} -\item{composite}{a logical parameter indicating if the composite maps are computed or not (default = FALSE).} +\item{composite}{A logical parameter indicating if the composite maps are +computed or not (default = FALSE).} -\item{memb}{a logical value indicating whether to compute composites for separate members (default FALSE) or as unique ensemble (TRUE). -This option is only available for when parameter 'composite' is set to TRUE and the data object has a dimension named 'member'.} +\item{memb}{A logical value indicating whether to compute composites for +separate members (default FALSE) or as unique ensemble (TRUE). This option +is only available for when parameter 'composite' is set to TRUE and the data +object has a dimension named 'member'.} -\item{ncores}{the number of multicore threads to use for parallel computation.} +\item{ncores}{The number of multicore threads to use for parallel computation.} } \value{ -A list with two elements \code{$data} (a 's2dv_cube' object containing the composites cluster=1,..,K for case (*1) - \code{$pvalue} (array with the same structure as \code{$data} containing the pvalue of the composites obtained through a t-test - that accounts for the serial dependence of the data with the same structure as Composite.)(only when composite = 'TRUE'), - \code{$cluster} (array with the same dimensions as data (except latitude and longitude which are removed) indicating the ref_maps to which each point is allocated.) , - \code{$frequency} (A vector of integers (from k=1,...k n reference maps) indicating the percentage of assignations corresponding to each map.), +A list with two elements \code{$data} (a 's2dv_cube' object containing +the composites cluster=1,..,K for case (*1) or only k=1 for any specific +cluster, i.e., case (*2)) (only when composite = 'TRUE') and \code{$statistics} +that includes \code{$pvalue} (array with the same structure as \code{$data} +containing the pvalue of the composites obtained through a t-test that +accounts for the serial dependence of the data with the same structure as +Composite.)(only when composite = 'TRUE'), \code{$cluster} (array with the +same dimensions as data (except latitude and longitude which are removed) +indicating the ref_maps to which each point is allocated.), \code{$frequency} +(A vector of integers (from k=1,...k n reference maps) indicating the +percentage of assignations corresponding to each map.). } \description{ -This function performs the matching between a field of anomalies and a set -of maps which will be used as a reference. The anomalies will be assigned to the reference map -for which the minimum Eucledian distance (method=’distance’) or highest spatial correlation -(method = 'ACC') is obtained. +This function performs the matching between a field of anomalies +and a set of maps which will be used as a reference. The anomalies will be +assigned to the reference map for which the minimum Eucledian distance +(method=’distance’) or highest spatial correlation (method = 'ACC') is +obtained. } \examples{ \dontrun{ -regimes <- CST_WeatherRegimes(data = lonlat_temp$obs, EOFs = FALSE, ncenters = 4) -res1 <- CST_RegimesAssign(data = lonlat_temp$exp, ref_maps = regimes, composite = FALSE) -res2 <- CST_RegimesAssign(data = lonlat_temp$exp, ref_maps = regimes, composite = TRUE) +regimes <- CST_WeatherRegimes(data = lonlat_temp$obs, EOFs = FALSE, + ncenters = 4) +res1 <- CST_RegimesAssign(data = lonlat_temp$exp, ref_maps = regimes, + composite = FALSE) +res2 <- CST_RegimesAssign(data = lonlat_temp$exp, ref_maps = regimes, + composite = TRUE) } } \references{ -Torralba, V. (2019) Seasonal climate prediction for the wind energy sector: methods and tools -for the development of a climate service. Thesis. Available online: \url{https://eprints.ucm.es/56841/} +Torralba, V. (2019) Seasonal climate prediction for the wind +energy sector: methods and tools for the development of a climate service. +Thesis. Available online: \url{https://eprints.ucm.es/56841/} } \author{ Verónica Torralba - BSC, \email{veronica.torralba@bsc.es} diff --git a/man/CST_SaveExp.Rd b/man/CST_SaveExp.Rd index 787d1bd77b21e317bf757af4262e7de7283ab822..8c8ada305053496a1e0ae6e396c74b772f4fb52a 100644 --- a/man/CST_SaveExp.Rd +++ b/man/CST_SaveExp.Rd @@ -8,15 +8,18 @@ data in NetCDF format} CST_SaveExp(data, destination = "./CST_Data", extra_string = NULL) } \arguments{ -\item{data}{an object of class \code{s2dv_cube}.} +\item{data}{An object of class \code{s2dv_cube}.} -\item{destination}{a character string containing the directory name in which +\item{destination}{A character string containing the directory name in which to save the data. NetCDF file for each starting date are saved into the -folder tree: destination/experiment/variable/. By default the function +folder tree: \cr +destination/experiment/variable/. By default the function creates and saves the data into the folder "CST_Data" in the working directory.} -\item{extra_string}{a character string to be include as part of the file name, for instance, to identify member or realization. It would be added to the file name between underscore characters.} +\item{extra_string}{A character string to be include as part of the file name, +for instance, to identify member or realization. It would be added to the +file name between underscore characters.} } \description{ This function allows to divide and save a object of class diff --git a/man/CST_SplitDim.Rd b/man/CST_SplitDim.Rd index 80a94da3c8735a4fe76ecb202af69d788732bf36..9c23a38467fff510943d1427f35e889e50ba7f56 100644 --- a/man/CST_SplitDim.Rd +++ b/man/CST_SplitDim.Rd @@ -14,23 +14,42 @@ CST_SplitDim( ) } \arguments{ -\item{data}{a 's2dv_cube' object} +\item{data}{A 's2dv_cube' object} -\item{split_dim}{a character string indicating the name of the dimension to split} +\item{split_dim}{A character string indicating the name of the dimension to +split.} -\item{indices}{a vector of numeric indices or dates. If left at NULL, the dates provided in the s2dv_cube object (element Dates) will be used.} +\item{indices}{A vector of numeric indices or dates. If left at NULL, the +dates provided in the s2dv_cube object (element Dates) will be used.} -\item{freq}{a character string indicating the frequency: by 'day', 'month' and 'year' or 'monthly' (by default). 'month' identifies months between 1 and 12 independently of the year they belong to, while 'monthly' differenciates months from different years.} +\item{freq}{A character string indicating the frequency: by 'day', 'month' and +'year' or 'monthly' (by default). 'month' identifies months between 1 and 12 +independently of the year they belong to, while 'monthly' differenciates +months from different years.} -\item{new_dim_name}{a character string indicating the name of the new dimension.} +\item{new_dim_name}{A character string indicating the name of the new dimension.} -\item{insert_ftime}{an integer indicating the number of time steps to add at the begining of the time series.} +\item{insert_ftime}{An integer indicating the number of time steps to add at +the begining of the time series.} } \description{ -This function split a dimension in two. The user can select the dimension to split and provide indices indicating how to split that dimension or dates and the frequency expected (monthly or by day, month and year). The user can also provide a numeric frequency indicating the length of each division. +This function split a dimension in two. The user can select the +dimension to split and provide indices indicating how to split that dimension +or dates and the frequency expected (monthly or by day, month and year). The +user can also provide a numeric frequency indicating the length of each division. } \details{ -Parameter 'insert_ftime' has been included for the case of using daily data, requiring split the temporal dimensions by months (or similar) and the first lead time doesn't correspondt to the 1st day of the month. In this case, the insert_ftime could be used, to get a final output correctly organized. E.g.: leadtime 1 is the 2nd of November and the input time series extend to the 31st of December. When requiring split by month with \code{inset_ftime = 1}, the 'monthly' dimension of length two will indicate the month (position 1 for November and position 2 for December), dimension 'time' will be length 31. For November, the position 1 and 31 will be NAs, while from positon 2 to 30 will be filled with the data provided. This allows to select correctly days trhough time dimension. +Parameter 'insert_ftime' has been included for the case of using +daily data, requiring split the temporal dimensions by months (or similar) and +the first lead time doesn't correspondt to the 1st day of the month. In this +case, the insert_ftime could be used, to get a final output correctly +organized. E.g.: leadtime 1 is the 2nd of November and the input time series +extend to the 31st of December. When requiring split by month with +\code{inset_ftime = 1}, the 'monthly' dimension of length two will indicate +the month (position 1 for November and position 2 for December), dimension +'time' will be length 31. For November, the position 1 and 31 will be NAs, +while from positon 2 to 30 will be filled with the data provided. This allows +to select correctly days trhough time dimension. } \examples{ diff --git a/man/CST_WeatherRegimes.Rd b/man/CST_WeatherRegimes.Rd index 64b24eec9d1bc23648aef017bb369aa1c61e9d9f..388affbc26f63e4ae4a2488b3db7faeda7f8a132 100644 --- a/man/CST_WeatherRegimes.Rd +++ b/man/CST_WeatherRegimes.Rd @@ -17,40 +17,55 @@ CST_WeatherRegimes( ) } \arguments{ -\item{data}{a 's2dv_cube' object} +\item{data}{An 's2dv_cube' object} -\item{ncenters}{Number of clusters to be calculated with the clustering function.} +\item{ncenters}{Number of clusters to be calculated with the clustering +function.} -\item{EOFs}{Whether to compute the EOFs (default = 'TRUE') or not (FALSE) to filter the data.} +\item{EOFs}{Whether to compute the EOFs (default = 'TRUE') or not (FALSE) to +filter the data.} -\item{neofs}{number of modes to be kept (default = 30).} +\item{neofs}{Number of modes to be kept (default = 30).} -\item{varThreshold}{Value with the percentage of variance to be explained by the PCs. -Only sufficient PCs to explain this much variance will be used in the clustering.} +\item{varThreshold}{Value with the percentage of variance to be explained by +the PCs. Only sufficient PCs to explain this much variance will be used in +the clustering.} -\item{method}{Different options to estimate the clusters. The most traditional approach is the k-means analysis (default=’kmeans’) -but the function also support the different methods included in the hclust . These methods are: -"ward.D", "ward.D2", "single", "complete", "average" (= UPGMA), "mcquitty" (= WPGMA), "median" (= WPGMC) or "centroid" (= UPGMC). -For more details about these methods see the hclust function documentation included in the stats package.} +\item{method}{Different options to estimate the clusters. The most traditional +approach is the k-means analysis (default=’kmeans’) but the function also +support the different methods included in the hclust . These methods are: +"ward.D", "ward.D2", "single", "complete", "average" (= UPGMA), "mcquitty" +(= WPGMA), "median" (= WPGMC) or "centroid" (= UPGMC). For more details +about these methods see the hclust function documentation included in the +stats package.} -\item{iter.max}{Parameter to select the maximum number of iterations allowed (Only if method='kmeans' is selected).} +\item{iter.max}{Parameter to select the maximum number of iterations allowed +(Only if method='kmeans' is selected).} -\item{nstart}{Parameter for the cluster analysis determining how many random sets to choose (Only if method='kmeans' is selected).} +\item{nstart}{Parameter for the cluster analysis determining how many random +sets to choose (Only if method='kmeans' is selected).} \item{ncores}{The number of multicore threads to use for parallel computation.} } \value{ -A list with two elements \code{$data} (a 's2dv_cube' object containing the composites cluster=1,..,K for case (*1) - \code{$pvalue} (array with the same structure as \code{$data} containing the pvalue of the composites obtained through a t-test that accounts for the serial dependence.), - \code{cluster} (A matrix or vector with integers (from 1:k) indicating the cluster to which each time step is allocated.), - \code{persistence} (Percentage of days in a month/season before a cluster is replaced for a new one (only if method=’kmeans’ has been selected.)), - \code{frequency} (Percentage of days in a month/season belonging to each cluster (only if method=’kmeans’ has been selected).), +A list with two elements \code{$data} (a 's2dv_cube' object containing +the composites cluster = 1,..,K for case (*1) or only k = 1 for any specific +cluster, i.e., case (*2)) and \code{$statistics} that includes \code{$pvalue} +(array with the same structure as \code{$data} containing the pvalue of the +composites obtained through a t-test that accounts for the serial dependence.), +\code{cluster} (A matrix or vector with integers (from 1:k) indicating the +cluster to which each time step is allocated.), \code{persistence} (Percentage +of days in a month/season before a cluster is replaced for a new one (only if +method=’kmeans’ has been selected.)), \code{frequency} (Percentage of days in +a month/season belonging to each cluster (only if method=’kmeans’ has been +selected).), } \description{ -This function computes the weather regimes from a cluster analysis. -It is applied on the array \code{data} in a 's2dv_cube' object. The dimensionality of this object can be also reduced -by using PCs obtained from the application of the #'EOFs analysis to filter the dataset. -The cluster analysis can be performed with the traditional k-means or those methods +This function computes the weather regimes from a cluster +analysis. It is applied on the array \code{data} in a 's2dv_cube' object. The +dimensionality of this object can be also reduced by using PCs obtained from +the application of the #'EOFs analysis to filter the dataset. The cluster +analysis can be performed with the traditional k-means or those methods included in the hclust (stats package). } \examples{ @@ -60,12 +75,13 @@ res2 <- CST_WeatherRegimes(data = lonlat_temp$obs, EOFs = TRUE, ncenters = 3) } } \references{ -Cortesi, N., V., Torralba, N., González-Reviriego, A., Soret, and F.J., Doblas-Reyes (2019). -Characterization of European wind speed variability using weather regimes. Climate Dynamics,53, -4961–4976, doi:10.1007/s00382-019-04839-5. +Cortesi, N., V., Torralba, N., González-Reviriego, A., Soret, and +F.J., Doblas-Reyes (2019). Characterization of European wind speed variability +using weather regimes. Climate Dynamics,53, 4961–4976, doi:10.1007/s00382-019-04839-5. -Torralba, V. (2019) Seasonal climate prediction for the wind energy sector: methods and tools -for the development of a climate service. Thesis. Available online: \url{https://eprints.ucm.es/56841/} +Torralba, V. (2019) Seasonal climate prediction for the wind +energy sector: methods and tools for the development of a climate service. +Thesis. Available online: \url{https://eprints.ucm.es/56841/}. } \author{ Verónica Torralba - BSC, \email{veronica.torralba@bsc.es} diff --git a/man/Calibration.Rd b/man/Calibration.Rd index 8b0b5231a4abdf8666c8c19fe2d6c3540107689e..5e2e0e5bda915e19f03ffacdd01547b1a03a49a2 100644 --- a/man/Calibration.Rd +++ b/man/Calibration.Rd @@ -21,42 +21,95 @@ Calibration( ) } \arguments{ -\item{exp}{a multidimensional array with named dimensions (at least 'sdate' and 'member') containing the seasonal hindcast experiment data. The hindcast is used to calibrate the forecast in case the forecast is provided; if not, the same hindcast will be calibrated instead.} - -\item{obs}{a multidimensional array with named dimensions (at least 'sdate') containing the observed data.} - -\item{exp_cor}{an optional multidimensional array with named dimensions (at least 'sdate' and 'member') containing the seasonal forecast experiment data. If the forecast is provided, it will be calibrated using the hindcast and observations; if not, the hindcast will be calibrated instead.} - -\item{cal.method}{is the calibration method used, can be either \code{bias}, \code{evmos}, \code{mse_min}, \code{crps_min} or \code{rpc-based}. Default value is \code{mse_min}.} - -\item{eval.method}{is the sampling method used, can be either \code{in-sample} or \code{leave-one-out}. Default value is the \code{leave-one-out} cross validation. In case the forecast is provided, any chosen eval.method is over-ruled and a third option is used.} - -\item{multi.model}{is a boolean that is used only for the \code{mse_min} method. If multi-model ensembles or ensembles of different sizes are used, it must be set to \code{TRUE}. By default it is \code{FALSE}. Differences between the two approaches are generally small but may become large when using small ensemble sizes. Using multi.model when the calibration method is \code{bias}, \code{evmos} or \code{crps_min} will not affect the result.} - -\item{na.fill}{is a boolean that indicates what happens in case calibration is not possible or will yield unreliable results. This happens when three or less forecasts-observation pairs are available to perform the training phase of the calibration. By default \code{na.fill} is set to true such that NA values will be returned. If \code{na.fill} is set to false, the uncorrected data will be returned.} - -\item{na.rm}{is a boolean that indicates whether to remove the NA values or not. The default value is \code{TRUE}.} - -\item{apply_to}{is a character string that indicates whether to apply the calibration to all the forecast (\code{"all"}) or only to those where the correlation between the ensemble mean and the observations is statistically significant (\code{"sign"}). Only useful if \code{cal.method == "rpc-based"}.} - -\item{alpha}{is a numeric value indicating the significance level for the correlation test. Only useful if \code{cal.method == "rpc-based" & apply_to == "sign"}.} - -\item{memb_dim}{is a character string indicating the name of the member dimension. By default, it is set to 'member'.} - -\item{sdate_dim}{is a character string indicating the name of the start date dimension. By default, it is set to 'sdate'.} - -\item{ncores}{is an integer that indicates the number of cores for parallel computations using multiApply function. The default value is one.} +\item{exp}{A multidimensional array with named dimensions (at least 'sdate' +and 'member') containing the seasonal hindcast experiment data. The hindcast +is used to calibrate the forecast in case the forecast is provided; if not, +the same hindcast will be calibrated instead.} + +\item{obs}{A multidimensional array with named dimensions (at least 'sdate') +containing the observed data.} + +\item{exp_cor}{An optional multidimensional array with named dimensions (at +least 'sdate' and 'member') containing the seasonal forecast experiment data. +If the forecast is provided, it will be calibrated using the hindcast and +observations; if not, the hindcast will be calibrated instead.} + +\item{cal.method}{Is the calibration method used, can be either \code{bias}, +\code{evmos}, \code{mse_min}, \code{crps_min} or \code{rpc-based}. Default +value is \code{mse_min}.} + +\item{eval.method}{Is the sampling method used, can be either \code{in-sample} +or \code{leave-one-out}. Default value is the \code{leave-one-out} cross +validation. In case the forecast is provided, any chosen eval.method is +over-ruled and a third option is used.} + +\item{multi.model}{Is a boolean that is used only for the \code{mse_min} +method. If multi-model ensembles or ensembles of different sizes are used, +it must be set to \code{TRUE}. By default it is \code{FALSE}. Differences +between the two approaches are generally small but may become large when +using small ensemble sizes. Using multi.model when the calibration method is +\code{bias}, \code{evmos} or \code{crps_min} will not affect the result.} + +\item{na.fill}{Is a boolean that indicates what happens in case calibration is +not possible or will yield unreliable results. This happens when three or +less forecasts-observation pairs are available to perform the training phase +of the calibration. By default \code{na.fill} is set to true such that NA +values will be returned. If \code{na.fill} is set to false, the uncorrected +data will be returned.} + +\item{na.rm}{Is a boolean that indicates whether to remove the NA values or +not. The default value is \code{TRUE}.} + +\item{apply_to}{Is a character string that indicates whether to apply the +calibration to all the forecast (\code{"all"}) or only to those where the +correlation between the ensemble mean and the observations is statistically +significant (\code{"sign"}). Only useful if \code{cal.method == "rpc-based"}.} + +\item{alpha}{Is a numeric value indicating the significance level for the +correlation test. Only useful if \code{cal.method == "rpc-based" & +apply_to == "sign"}.} + +\item{memb_dim}{Is a character string indicating the name of the member +dimension. By default, it is set to 'member'.} + +\item{sdate_dim}{Is a character string indicating the name of the start date +dimension. By default, it is set to 'sdate'.} + +\item{ncores}{Is an integer that indicates the number of cores for parallel +computations using multiApply function. The default value is one.} } \value{ -an array containing the calibrated forecasts with the same dimensions as the \code{exp} array. +An array containing the calibrated forecasts with the same dimensions +as the \code{exp} array. } \description{ -Five types of member-by-member bias correction can be performed. The \code{"bias"} method corrects the bias only, the \code{"evmos"} method applies a variance inflation technique to ensure the correction of the bias and the correspondence of variance between forecast and observation (Van Schaeybroeck and Vannitsem, 2011). The ensemble calibration methods \code{"mse_min"} and \code{"crps_min"} correct the bias, the overall forecast variance and the ensemble spread as described in Doblas-Reyes et al. (2005) and Van Schaeybroeck and Vannitsem (2015), respectively. While the \code{"mse_min"} method minimizes a constrained mean-squared error using three parameters, the \code{"crps_min"} method features four parameters and minimizes the Continuous Ranked Probability Score (CRPS). The \code{"rpc-based"} method adjusts the forecast variance ensuring that the ratio of predictable components (RPC) is equal to one, as in Eade et al. (2014). - -Both in-sample or our out-of-sample (leave-one-out cross validation) calibration are possible. +Five types of member-by-member bias correction can be performed. +The \code{"bias"} method corrects the bias only, the \code{"evmos"} method +applies a variance inflation technique to ensure the correction of the bias +and the correspondence of variance between forecast and observation (Van +Schaeybroeck and Vannitsem, 2011). The ensemble calibration methods +\code{"mse_min"} and \code{"crps_min"} correct the bias, the overall forecast +variance and the ensemble spread as described in Doblas-Reyes et al. (2005) +and Van Schaeybroeck and Vannitsem (2015), respectively. While the +\code{"mse_min"} method minimizes a constrained mean-squared error using three +parameters, the \code{"crps_min"} method features four parameters and +minimizes the Continuous Ranked Probability Score (CRPS). The +\code{"rpc-based"} method adjusts the forecast variance ensuring that the +ratio of predictable components (RPC) is equal to one, as in Eade et al. (2014). + +Both in-sample or our out-of-sample (leave-one-out cross +validation) calibration are possible. } \details{ -Both the \code{na.fill} and \code{na.rm} parameters can be used to indicate how the function has to handle the NA values. The \code{na.fill} parameter checks whether there are more than three forecast-observations pairs to perform the computation. In case there are three or less pairs, the computation is not carried out, and the value returned by the function depends on the value of this parameter (either NA if \code{na.fill == TRUE} or the uncorrected value if \code{na.fill == TRUE}). On the other hand, \code{na.rm} is used to indicate the function whether to remove the missing values during the computation of the parameters needed to perform the calibration. +Both the \code{na.fill} and \code{na.rm} parameters can be used to indicate +how the function has to handle the NA values. The \code{na.fill} parameter +checks whether there are more than three forecast-observations pairs to +perform the computation. In case there are three or less pairs, the +computation is not carried out, and the value returned by the function depends +on the value of this parameter (either NA if \code{na.fill == TRUE} or the +uncorrected value if \code{na.fill == TRUE}). On the other hand, \code{na.rm} +is used to indicate the function whether to remove the missing values during +the computation of the parameters needed to perform the calibration. } \examples{ mod1 <- 1 : (1 * 3 * 4 * 5 * 6 * 7) @@ -67,13 +120,24 @@ a <- Calibration(exp = mod1, obs = obs1) str(a) } \references{ -Doblas-Reyes F.J, Hagedorn R, Palmer T.N. The rationale behind the success of multi-model ensembles in seasonal forecasting-II calibration and combination. Tellus A. 2005;57:234-252. doi:10.1111/j.1600-0870.2005.00104.x - -Eade, R., Smith, D., Scaife, A., Wallace, E., Dunstone, N., Hermanson, L., & Robinson, N. (2014). Do seasonal-to-decadal climate predictions underestimate the predictability of the read world? Geophysical Research Letters, 41(15), 5620-5628. doi: 10.1002/2014GL061146 - -Van Schaeybroeck, B., & Vannitsem, S. (2011). Post-processing through linear regression. Nonlinear Processes in Geophysics, 18(2), 147. doi:10.5194/npg-18-147-2011 - -Van Schaeybroeck, B., & Vannitsem, S. (2015). Ensemble post-processing using member-by-member approaches: theoretical aspects. Quarterly Journal of the Royal Meteorological Society, 141(688), 807-818. doi:10.1002/qj.2397 +Doblas-Reyes F.J, Hagedorn R, Palmer T.N. The rationale behind the +success of multi-model ensembles in seasonal forecasting-II calibration and +combination. Tellus A. 2005;57:234-252. +doi:10.1111/j.1600-0870.2005.00104.x + +Eade, R., Smith, D., Scaife, A., Wallace, E., Dunstone, N., +Hermanson, L., & Robinson, N. (2014). Do seasonal-to-decadal climate +predictions underestimate the predictability of the read world? Geophysical +Research Letters, 41(15), 5620-5628. doi: 10.1002/2014GL061146 + +Van Schaeybroeck, B., & Vannitsem, S. (2011). Post-processing +through linear regression. Nonlinear Processes in Geophysics, 18(2), 147. +doi:10.5194/npg-18-147-2011 + +Van Schaeybroeck, B., & Vannitsem, S. (2015). Ensemble +post-processing using member-by-member approaches: theoretical aspects. +Quarterly Journal of the Royal Meteorological Society, 141(688), 807-818. +doi:10.1002/qj.2397 } \seealso{ \code{\link{CST_Load}} diff --git a/man/CategoricalEnsCombination.Rd b/man/CategoricalEnsCombination.Rd index 2f5ad14d69ba9db0ea970da8bc340ec73f66e2a1..c3599d032e4b76643c844d01b2ebac2a9dd20869 100644 --- a/man/CategoricalEnsCombination.Rd +++ b/man/CategoricalEnsCombination.Rd @@ -2,41 +2,66 @@ % Please edit documentation in R/CST_CategoricalEnsCombination.R \name{CategoricalEnsCombination} \alias{CategoricalEnsCombination} -\title{Make categorical forecast based on a multi-model forecast with potential for calibrate} +\title{Make categorical forecast based on a multi-model forecast with potential for +calibrate} \usage{ CategoricalEnsCombination(fc, obs, cat.method, eval.method, amt.cat, ...) } \arguments{ -\item{fc}{a multi-dimensional array with named dimensions containing the seasonal forecast experiment data in the element named \code{$data}. The amount of forecasting models is equal to the size of the \code{dataset} dimension of the data array. The amount of members per model may be different. The size of the \code{member} dimension of the data array is equal to the maximum of the ensemble members among the models. Models with smaller ensemble sizes have residual indices of \code{member} dimension in the data array filled with NA values.} +\item{fc}{A multi-dimensional array with named dimensions containing the +seasonal forecast experiment data in the element named \code{$data}. The +amount of forecasting models is equal to the size of the \code{dataset} +dimension of the data array. The amount of members per model may be +different. The size of the \code{member} dimension of the data array is +equal to the maximum of the ensemble members among the models. Models with +smaller ensemble sizes have residual indices of \code{member} dimension in +the data array filled with NA values.} -\item{obs}{a multidimensional array with named dimensions containing the observed data in the element named \code{$data}.} +\item{obs}{A multidimensional array with named dimensions containing the +observed data in the element named \code{$data}.} -\item{cat.method}{method used to produce the categorical forecast, can be either \code{pool}, \code{comb}, \code{mmw} or \code{obs}. The method pool assumes equal weight for all ensemble members while the method comb assumes equal weight for each model. The weighting method is descirbed in Rajagopalan et al. (2002), Robertson et al. (2004) and Van Schaeybroeck and Vannitsem (2019). Finally, the \code{obs} method classifies the observations into the different categories and therefore contains only 0 and 1 values.} +\item{cat.method}{Method used to produce the categorical forecast, can be +either \code{pool}, \code{comb}, \code{mmw} or \code{obs}. The method pool +assumes equal weight for all ensemble members while the method comb assumes +equal weight for each model. The weighting method is descirbed in +Rajagopalan et al. (2002), Robertson et al. (2004) and Van Schaeybroeck and +Vannitsem (2019). Finally, the \code{obs} method classifies the observations +into the different categories and therefore contains only 0 and 1 values.} -\item{eval.method}{is the sampling method used, can be either \code{"in-sample"} or \code{"leave-one-out"}. Default value is the \code{"leave-one-out"} cross validation.} +\item{eval.method}{Is the sampling method used, can be either +\code{"in-sample"} or \code{"leave-one-out"}. Default value is the +\code{"leave-one-out"} cross validation.} -\item{amt.cat}{is the amount of categories. Equally-sized quantiles will be calculated based on the amount of categories.} +\item{amt.cat}{Is the amount of categories. Equally-sized quantiles will be +calculated based on the amount of categories.} -\item{...}{other parameters to be passed on to the calibration procedure.} +\item{...}{Other parameters to be passed on to the calibration procedure.} } \value{ -an array containing the categorical forecasts in the element called \code{$data}. The first two dimensions of the returned object are named dataset and member and are both of size one. An additional dimension named category is introduced and is of size amt.cat. +An array containing the categorical forecasts in the element called +\code{$data}. The first two dimensions of the returned object are named +dataset and member and are both of size one. An additional dimension named +category is introduced and is of size amt.cat. } \description{ -This function converts a multi-model ensemble forecast -into a categorical forecast by giving the probability -for each category. Different methods are available to combine -the different ensemble forecasting models into -probabilistic categorical forecasts. +This function converts a multi-model ensemble forecast into a +categorical forecast by giving the probability for each category. Different +methods are available to combine the different ensemble forecasting models +into probabilistic categorical forecasts. See details in ?CST_CategoricalEnsCombination } \references{ -Rajagopalan, B., Lall, U., & Zebiak, S. E. (2002). Categorical climate forecasts through regularization and optimal combination of multiple GCM ensembles. Monthly Weather Review, 130(7), 1792-1811. +Rajagopalan, B., Lall, U., & Zebiak, S. E. (2002). Categorical +climate forecasts through regularization and optimal combination of multiple +GCM ensembles. Monthly Weather Review, 130(7), 1792-1811. -Robertson, A. W., Lall, U., Zebiak, S. E., & Goddard, L. (2004). Improved combination of multiple atmospheric GCM ensembles for seasonal prediction. Monthly Weather Review, 132(12), 2732-2744. +Robertson, A. W., Lall, U., Zebiak, S. E., & Goddard, L. (2004). +Improved combination of multiple atmospheric GCM ensembles for seasonal +prediction. Monthly Weather Review, 132(12), 2732-2744. -Van Schaeybroeck, B., & Vannitsem, S. (2019). Postprocessing of Long-Range Forecasts. In Statistical Postprocessing of Ensemble Forecasts (pp. 267-290). +Van Schaeybroeck, B., & Vannitsem, S. (2019). Postprocessing of +Long-Range Forecasts. In Statistical Postprocessing of Ensemble Forecasts (pp. 267-290). } \author{ Bert Van Schaeybroeck, \email{bertvs@meteo.be} diff --git a/man/DynBiasCorrection.Rd b/man/DynBiasCorrection.Rd index e6de373c814712165465b15d2f7802167b52982a..e82ca8c7215b8d60ff546a367d048ab378f4ee35 100644 --- a/man/DynBiasCorrection.Rd +++ b/man/DynBiasCorrection.Rd @@ -16,32 +16,32 @@ DynBiasCorrection( ) } \arguments{ -\item{exp}{a multidimensional array with named dimensions with the -experiment data} +\item{exp}{A multidimensional array with named dimensions with the +experiment data.} -\item{obs}{a multidimensional array with named dimensions with the -observation data} +\item{obs}{A multidimensional array with named dimensions with the +observation data.} -\item{method}{a character string indicating the method to apply bias +\item{method}{A character string indicating the method to apply bias correction among these ones: -"PTF","RQUANT","QUANT","SSPLIN"} +"PTF", "RQUANT", "QUANT", "SSPLIN".} -\item{wetday}{logical indicating whether to perform wet day correction +\item{wetday}{Logical indicating whether to perform wet day correction or not OR a numeric threshold below which all values are set to zero (by default is set to 'FALSE').} -\item{proxy}{a character string indicating the proxy for local dimension +\item{proxy}{A character string indicating the proxy for local dimension 'dim' or inverse of persistence 'theta' to apply the dynamical conditioned bias correction method.} -\item{quanti}{a number lower than 1 indicating the quantile to perform the -computation of local dimension and theta} +\item{quanti}{A number lower than 1 indicating the quantile to perform the +computation of local dimension and theta.} -\item{ncores}{The number of cores to use in parallel computation} +\item{ncores}{The number of cores to use in parallel computation.} } \value{ -a multidimensional array with named dimensions with a bias correction -performed conditioned by local dimension 'dim' or inverse of persistence 'theta' +A multidimensional array with named dimensions with a bias correction +performed conditioned by local dimension 'dim' or inverse of persistence 'theta'. } \description{ This function perform a bias correction conditioned by the @@ -60,7 +60,7 @@ dim (expL) <- c(time =100,lat = 4, lon = 5) obsL <- c(rnorm(1:1980),expL[1,,]*1.2) dim (obsL) <- c(time = 100,lat = 4, lon = 5) dynbias <- DynBiasCorrection(exp = expL, obs = obsL, method='QUANT', - proxy= "dim", quanti = 0.6) + proxy= "dim", quanti = 0.6) } \references{ Faranda, D., Alvarez-Castro, M.C., Messori, G., Rodriguez, D., diff --git a/man/EnsClustering.Rd b/man/EnsClustering.Rd index e9409932e27021e890683f6806d9a487e5b0228f..f7b73266740bb24ee00245170972dda850ebc312 100644 --- a/man/EnsClustering.Rd +++ b/man/EnsClustering.Rd @@ -21,57 +21,63 @@ EnsClustering( ) } \arguments{ -\item{data}{A matrix of dimensions 'dataset member sdate ftime lat lon' containing the variables to be analysed.} +\item{data}{A matrix of dimensions 'dataset member sdate ftime lat lon' +containing the variables to be analysed.} \item{lat}{Vector of latitudes.} \item{lon}{Vector of longitudes.} -\item{time_moment}{Decides the moment to be applied to the time dimension. Can be either 'mean' (time mean), -'sd' (standard deviation along time) or 'perc' (a selected percentile on time). -If 'perc' the keyword 'time_percentile' is also used.} +\item{time_moment}{Decides the moment to be applied to the time dimension. Can +be either 'mean' (time mean), 'sd' (standard deviation along time) or 'perc' +(a selected percentile on time). If 'perc' the keyword 'time_percentile' is +also used.} -\item{numclus}{Number of clusters (scenarios) to be calculated. -If set to NULL the number of ensemble members divided by 10 is used, with a minimum of 2 and a maximum of 8.} +\item{numclus}{Number of clusters (scenarios) to be calculated. If set to NULL +the number of ensemble members divided by 10 is used, with a minimum of 2 +and a maximum of 8.} \item{lon_lim}{List with the two longitude margins in `c(-180,180)` format.} \item{lat_lim}{List with the two latitude margins.} -\item{variance_explained}{variance (percentage) to be explained by the set of EOFs. -Defaults to 80. Not used if numpcs is specified.} +\item{variance_explained}{variance (percentage) to be explained by the set of +EOFs. Defaults to 80. Not used if numpcs is specified.} \item{numpcs}{Number of EOFs retained in the analysis (optional).} -\item{time_percentile}{Set the percentile in time you want to analyse (used for `time_moment = "perc").} +\item{time_percentile}{Set the percentile in time you want to analyse (used +for `time_moment = "perc").} -\item{time_dim}{String or character array with name(s) of dimension(s) over which to compute statistics. -If omitted c("ftime", "sdate", "time") are searched in this order.} +\item{time_dim}{String or character array with name(s) of dimension(s) over +which to compute statistics. If omitted c("ftime", "sdate", "time") are +searched in this order.} -\item{cluster_dim}{Dimension along which to cluster. Typically "member" or "sdate". -This can also be a list like c("member", "sdate").} +\item{cluster_dim}{Dimension along which to cluster. Typically "member" or +"sdate". This can also be a list like c("member", "sdate").} \item{verbose}{Logical for verbose output} } \value{ A list with elements \code{$cluster} (cluster assigned for each member), - \code{$freq} (relative frequency of each cluster), \code{$closest_member} - (representative member for each cluster), \code{$repr_field} (list of fields - for each representative member), \code{composites} (list of mean fields for each cluster), - \code{$lon} (selected longitudes of output fields), - \code{$lat} (selected longitudes of output fields). +\code{$freq} (relative frequency of each cluster), \code{$closest_member} +(representative member for each cluster), \code{$repr_field} (list of fields for +each representative member), \code{composites} (list of mean fields for each +cluster), \code{$lon} (selected longitudes of output fields), \code{$lat} +(selected longitudes of output fields). } \description{ This function performs a clustering on members/starting dates -and returns a number of scenarios, with representative members for each of them. -The clustering is performed in a reduced EOF space. +and returns a number of scenarios, with representative members for each of +them. The clustering is performed in a reduced EOF space. } \examples{ -\donttest{ exp <- lonlat_temp$exp -res <- EnsClustering(exp$data, exp$lat, exp$lon, numclus = 3, - cluster_dim = c("member", "dataset", "sdate")) -} +exp$data <- ClimProjDiags::Subset(exp$data, along = c('member', 'lat'), list(1:5, 1:10)) +exp$lat <- exp$lat[1:10] +res <- EnsClustering(exp$data, exp$lat, exp$lon, numclus = 2, + cluster_dim = c("member", "dataset", "sdate")) + } \author{ Federico Fabiano - ISAC-CNR, \email{f.fabiano@isac.cnr.it} diff --git a/man/MergeDims.Rd b/man/MergeDims.Rd index 7539ef6ef08a128c11591c5a98f4654dfb7f1f4e..b6c70c5872d6f1d1b25292f9bfbf696c75c4e599 100644 --- a/man/MergeDims.Rd +++ b/man/MergeDims.Rd @@ -12,19 +12,23 @@ MergeDims( ) } \arguments{ -\item{data}{an n-dimensional array with named dimensions} +\item{data}{An n-dimensional array with named dimensions} -\item{merge_dims}{a character vector indicating the names of the dimensions to merge} +\item{merge_dims}{A character vector indicating the names of the dimensions to +merge.} -\item{rename_dim}{a character string indicating the name of the output dimension. If left at NULL, the first dimension name provided in parameter \code{merge_dims} will be used.} +\item{rename_dim}{A character string indicating the name of the output +dimension. If left at NULL, the first dimension name provided in parameter +\code{merge_dims} will be used.} -\item{na.rm}{a logical indicating if the NA values should be removed or not.} +\item{na.rm}{A logical indicating if the NA values should be removed or not.} } \description{ -This function merges two dimensions of an array into one. The user can select the dimensions to merge and provide the final name of the dimension. The user can select to remove NA values or keep them. +This function merges two dimensions of an array into one. The +user can select the dimensions to merge and provide the final name of the +dimension. The user can select to remove NA values or keep them. } \examples{ - data <- 1 : 20 dim(data) <- c(time = 10, lat = 2) new_data <- MergeDims(data, merge_dims = c('time', 'lat')) diff --git a/man/MultiEOF.Rd b/man/MultiEOF.Rd index dd0fc7fe59e6a1c6606c2de2cbbceca6f0b4b15d..e80fbbbcad7737b3f20ac074563f3a4a23ad545e 100644 --- a/man/MultiEOF.Rd +++ b/man/MultiEOF.Rd @@ -2,7 +2,8 @@ % Please edit documentation in R/CST_MultiEOF.R \name{MultiEOF} \alias{MultiEOF} -\title{EOF analysis of multiple variables starting from an array (reduced version)} +\title{EOF analysis of multiple variables starting from an array (reduced +version)} \usage{ MultiEOF( data, @@ -19,9 +20,9 @@ MultiEOF( ) } \arguments{ -\item{data}{A multidimensional array with dimension \code{"var"}, -containing the variables to be analysed. The other diemnsions follow the same structure as the -\code{"exp"} element of a 's2dv_cube' object.} +\item{data}{A multidimensional array with dimension \code{"var"}, containing +the variables to be analysed. The other diemnsions follow the same structure +as the \code{"exp"} element of a 's2dv_cube' object.} \item{lon}{Vector of longitudes.} @@ -29,27 +30,45 @@ containing the variables to be analysed. The other diemnsions follow the same st \item{time}{Vector or matrix of dates in POSIXct format.} -\item{lon_dim}{String with dimension name of longitudinal coordinate} +\item{lon_dim}{String with dimension name of longitudinal coordinate.} -\item{lat_dim}{String with dimension name of latitudinal coordinate} +\item{lat_dim}{String with dimension name of latitudinal coordinate.} -\item{neof_max}{Maximum number of single eofs considered in the first decomposition} +\item{neof_max}{Maximum number of single eofs considered in the first +decomposition.} -\item{neof_composed}{Number of composed eofs to return in output} +\item{neof_composed}{Number of composed eofs to return in output.} -\item{minvar}{Minimum variance fraction to be explained in first decomposition} +\item{minvar}{Minimum variance fraction to be explained in first decomposition.} -\item{lon_lim}{Vector with longitudinal range limits for the calculation for all input variables} +\item{lon_lim}{Vector with longitudinal range limits for the calculation for +all input variables.} -\item{lat_lim}{Vector with latitudinal range limits for the calculation for all input variables} +\item{lat_lim}{Vector with latitudinal range limits for the calculation for +all input variables.} } \value{ -A list with elements \code{$coeff} (an array of time-varying principal component coefficients), - \code{$variance} (a matrix of explained variances), - \code{eof_pattern} (a matrix of EOF patterns obtained by regression for each variable). +A list with elements \code{$coeff} (an array of time-varying principal +component coefficients), \code{$variance} (a matrix of explained variances), +\code{eof_pattern} (a matrix of EOF patterns obtained by regression for each +variable). } \description{ -This function performs EOF analysis over multiple variables, accepting in input an array with a dimension \code{"var"} for each variable to analyse. Based on Singular Value Decomposition. For each field the EOFs are computed and the corresponding PCs are standardized (unit variance, zero mean); the minimum number of principal components needed to reach the user-defined variance is retained. The function weights the input data for the latitude cosine square root. +This function performs EOF analysis over multiple variables, +accepting in input an array with a dimension \code{"var"} for each variable to +analyse. Based on Singular Value Decomposition. For each field the EOFs are +computed and the corresponding PCs are standardized (unit variance, zero mean); +the minimum number of principal components needed to reach the user-defined +variance is retained. The function weights the input data for the latitude +cosine square root. +} +\examples{ +exp <- lonlat_temp$exp +exp$data <- ClimProjDiags::Subset(exp$data, c('member', 'lat', 'lon'), list(1:5, 1:4, 1:4)) +exp$lon <- exp$lon[1:4] +exp$lat <- exp$lat[1:4] +dim(exp$data) <- c(dim(exp$data), var = 1) +cal <- MultiEOF(data = exp$data, lon = exp$lon, lat = exp$lat, time = exp$Dates$start) } \author{ Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} diff --git a/man/MultiMetric.Rd b/man/MultiMetric.Rd index 252f735c475b17a765c26db830aebefcd8da0687..cd26141de3d9745e4fbf7dbaa95b08b2f918c8b5 100644 --- a/man/MultiMetric.Rd +++ b/man/MultiMetric.Rd @@ -15,34 +15,55 @@ MultiMetric( ) } \arguments{ -\item{exp}{a multidimensional array with named dimensions.} +\item{exp}{A multidimensional array with named dimensions.} -\item{obs}{a multidimensional array with named dimensions.} +\item{obs}{A multidimensional array with named dimensions.} -\item{metric}{a character string giving the metric for computing the maximum skill. This must be one of the strings 'correlation', 'rms' or 'rmsss.} +\item{metric}{A character string giving the metric for computing the maximum +skill. This must be one of the strings 'correlation', 'rms' or 'rmsss.} -\item{multimodel}{a logical value indicating whether a Multi-Model Mean should be computed.} +\item{multimodel}{A logical value indicating whether a Multi-Model Mean should +be computed.} -\item{time_dim}{name of the temporal dimension where a mean will be applied. It can be NULL, the default value is 'ftime'.} +\item{time_dim}{Name of the temporal dimension where a mean will be applied. +It can be NULL, the default value is 'ftime'.} -\item{memb_dim}{name of the member dimension. It can be NULL, the default value is 'member'.} +\item{memb_dim}{Name of the member dimension. It can be NULL, the default +value is 'member'.} -\item{sdate_dim}{name of the start date dimension or a dimension name identifiying the different forecast. It can be NULL, the default value is 'sdate'.} +\item{sdate_dim}{Name of the start date dimension or a dimension name +identifiying the different forecast. It can be NULL, the default value is +'sdate'.} } \value{ -a list of arrays containing the statistics of the selected metric in the element \code{$data} which is a list of arrays: for the metric requested and others for statistics about its signeificance. The arrays have two dataset dimensions equal to the 'dataset' dimension in the \code{exp$data} and \code{obs$data} inputs. If \code{multimodel} is TRUE, the greatest position in the first dimension correspons to the Multi-Model Mean. +A list of arrays containing the statistics of the selected metric in +the element \code{$data} which is a list of arrays: for the metric requested +and others for statistics about its signeificance. The arrays have two dataset +dimensions equal to the 'dataset' dimension in the \code{exp$data} and +\code{obs$data} inputs. If \code{multimodel} is TRUE, the greatest position in +the first dimension correspons to the Multi-Model Mean. } \description{ -This function calculates correlation (Anomaly Correlation Coefficient; ACC), root mean square error (RMS) and the root mean square error skill score (RMSSS) of individual anomaly models and multi-models mean (if desired) with the observations on arrays with named dimensions. +This function calculates correlation (Anomaly Correlation +Coefficient; ACC), root mean square error (RMS) and the root mean square error +skill score (RMSSS) of individual anomaly models and multi-models mean (if +desired) with the observations on arrays with named dimensions. } \examples{ -res <- MultiMetric(lonlat_temp$exp$data, lonlat_temp$obs$data) +exp <- array(rnorm(2 *2 * 4 * 5 * 2 * 2), + dim = c(dataset = 2, member = 2, sdate = 4, ftime = 5, lat = 2, lon = 2)) +obs <- array(rnorm(1 * 1 * 4 * 5 * 2 * 2), + c(dataset = 1, member = 1, sdate = 4, ftime = 5, lat = 2, lon = 2)) +res <- MultiMetric(exp = exp, obs = obs) } \references{ -Mishra, N., Prodhomme, C., & Guemas, V. (n.d.). Multi-Model Skill Assessment of Seasonal Temperature and Precipitation Forecasts over Europe, 29-31.\url{https://link.springer.com/article/10.1007/s00382-018-4404-z} +Mishra, N., Prodhomme, C., & Guemas, V. (n.d.). Multi-Model Skill +Assessment of Seasonal Temperature and Precipitation Forecasts over Europe, +29-31.\url{https://link.springer.com/article/10.1007/s00382-018-4404-z} } \seealso{ -\code{\link[s2dv]{Corr}}, \code{\link[s2dv]{RMS}}, \code{\link[s2dv]{RMSSS}} and \code{\link{CST_Load}} +\code{\link[s2dv]{Corr}}, \code{\link[s2dv]{RMS}}, +\code{\link[s2dv]{RMSSS}} and \code{\link{CST_Load}} } \author{ Mishra Niti, \email{niti.mishra@bsc.es} diff --git a/man/PlotForecastPDF.Rd b/man/PlotForecastPDF.Rd index c6442bbbc1aae7a3458d45db409cbea9d72fb9ee..7439506dc4b68779639c45f41e3cb8e7498126a0 100644 --- a/man/PlotForecastPDF.Rd +++ b/man/PlotForecastPDF.Rd @@ -76,14 +76,8 @@ included as hatched areas. Individual ensemble members can be plotted as jittered points. The observed value is optionally shown as a diamond. } \examples{ -fcsts <- data.frame(fcst1 = rnorm(10), fcst2 = rnorm(10, 0.5, 1.2), - fcst3 = rnorm(10, -0.5, 0.9)) +fcsts <- data.frame(fcst1 = rnorm(10), fcst2 = rnorm(10, 0.5, 1.2)) PlotForecastPDF(fcsts,c(-1,1)) -\donttest{ -fcsts2 <- array(rnorm(100), dim = c(member = 20, fcst = 5)) -PlotForecastPDF(fcsts2, c(-0.66, 0.66), extreme.limits = c(-1.2, 1.2), - fcst.names = paste0('random fcst ', 1 : 5), obs = 0.7) -} } \author{ Llorenç Lledó \email{llledo@bsc.es} diff --git a/man/PlotMostLikelyQuantileMap.Rd b/man/PlotMostLikelyQuantileMap.Rd index cc98f8f5c64adcb0fe71b8ec4435a2d392cf7107..c9a6ead2d6667606e5dc58216db504942c04fff6 100644 --- a/man/PlotMostLikelyQuantileMap.Rd +++ b/man/PlotMostLikelyQuantileMap.Rd @@ -16,17 +16,30 @@ PlotMostLikelyQuantileMap( ) } \arguments{ -\item{probs}{a list of bi-dimensional arrays with the named dimensions 'latitude' (or 'lat') and 'longitude' (or 'lon'), with equal size and in the same order, or a single tri-dimensional array with an additional dimension (e.g. 'bin') for the different categories. The arrays must contain probability values between 0 and 1, and the probabilities for all categories of a grid cell should not exceed 1 when added.} +\item{probs}{A list of bi-dimensional arrays with the named dimensions +'latitude' (or 'lat') and 'longitude' (or 'lon'), with equal size and in the +same order, or a single tri-dimensional array with an additional dimension +(e.g. 'bin') for the different categories. The arrays must contain +probability values between 0 and 1, and the probabilities for all categories +of a grid cell should not exceed 1 when added.} -\item{lon}{a numeric vector with the longitudes of the map grid, in the same order as the values along the corresponding dimension in \code{probs}.} +\item{lon}{A numeric vector with the longitudes of the map grid, in the same +order as the values along the corresponding dimension in \code{probs}.} -\item{lat}{a numeric vector with the latitudes of the map grid, in the same order as the values along the corresponding dimension in \code{probs}.} +\item{lat}{A numeric vector with the latitudes of the map grid, in the same +order as the values along the corresponding dimension in \code{probs}.} -\item{cat_dim}{the name of the dimension along which the different categories are stored in \code{probs}. This only applies if \code{probs} is provided in the form of 3-dimensional array. The default expected name is 'bin'.} +\item{cat_dim}{The name of the dimension along which the different categories +are stored in \code{probs}. This only applies if \code{probs} is provided in +the form of 3-dimensional array. The default expected name is 'bin'.} -\item{bar_titles}{vector of character strings with the names to be drawn on top of the color bar for each of the categories. As many titles as categories provided in \code{probs} must be provided.} +\item{bar_titles}{Vector of character strings with the names to be drawn on +top of the color bar for each of the categories. As many titles as +categories provided in \code{probs} must be provided.} -\item{col_unknown_cat}{character string with a colour representation of the colour to be used to paint the cells for which no category can be clearly assigned. Takes the value 'white' by default.} +\item{col_unknown_cat}{Character string with a colour representation of the +colour to be used to paint the cells for which no category can be clearly +assigned. Takes the value 'white' by default.} \item{drawleg}{Where to draw the common colour bar. Can take values TRUE, FALSE or:\cr @@ -35,10 +48,20 @@ FALSE or:\cr 'right', 'r', 'R', 'east', 'e', 'E'\cr 'left', 'l', 'L', 'west', 'w', 'W'} -\item{...}{additional parameters to be sent to \code{PlotCombinedMap} and \code{PlotEquiMap}.} +\item{...}{Additional parameters to be sent to \code{PlotCombinedMap} and +\code{PlotEquiMap}.} } \description{ -This function receives as main input (via the parameter \code{probs}) a collection of longitude-latitude maps, each containing the probabilities (from 0 to 1) of the different grid cells of belonging to a category. As many categories as maps provided as inputs are understood to exist. The maps of probabilities must be provided on a common rectangular regular grid, and a vector with the longitudes and a vector with the latitudes of the grid must be provided. The input maps can be provided in two forms, either as a list of multiple two-dimensional arrays (one for each category) or as a three-dimensional array, where one of the dimensions corresponds to the different categories. +This function receives as main input (via the parameter +\code{probs}) a collection of longitude-latitude maps, each containing the +probabilities (from 0 to 1) of the different grid cells of belonging to a +category. As many categories as maps provided as inputs are understood to +exist. The maps of probabilities must be provided on a common rectangular +regular grid, and a vector with the longitudes and a vector with the latitudes +of the grid must be provided. The input maps can be provided in two forms, +either as a list of multiple two-dimensional arrays (one for each category) or +as a three-dimensional array, where one of the dimensions corresponds to the +different categories. } \examples{ # Simple example @@ -133,5 +156,6 @@ PlotMostLikelyQuantileMap(bins, lons, lats, \code{PlotCombinedMap} and \code{PlotEquiMap} } \author{ -Veronica Torralba, \email{veronica.torralba@bsc.es}, Nicolau Manubens, \email{nicolau.manubens@bsc.es} +Veronica Torralba, \email{veronica.torralba@bsc.es}, Nicolau Manubens, +\email{nicolau.manubens@bsc.es} } diff --git a/man/PlotPDFsOLE.Rd b/man/PlotPDFsOLE.Rd index ff3c568e638a93870726d36d58d29d236c1aa2aa..e2c6606eb20822b0b29d40c99411dbb0de451710 100644 --- a/man/PlotPDFsOLE.Rd +++ b/man/PlotPDFsOLE.Rd @@ -25,7 +25,7 @@ to combining.} \item{pdf_2}{A numeric array with a dimension named 'statistic', containg two parameters: mean' and 'standard deviation' of the second gaussian pdf - to combining.} +to combining.} \item{nsigma}{(optional) A numeric value for setting the limits of X axis. (Default nsigma = 3).} @@ -68,20 +68,6 @@ attr(pdf_2, "name") <- "NAO2" dim(pdf_2) <- c(statistic = 2) PlotPDFsOLE(pdf_1, pdf_2) - -# Example 2 -Glosea5PDF <- c(2.25, 0.67) -attr(Glosea5PDF, "name") <- "Glosea5" -dim(Glosea5PDF) <- c(statistic = 2) -ECMWFPDF <- c(2.38, 0.61) -attr(ECMWFPDF, "name") <- "ECMWF" -dim(ECMWFPDF) <- c(statistic = 2) -MFPDF <- c(4.52, 0.34) -attr(MFPDF, "name") <- "MF" -dim(MFPDF) <- c(statistic = 2) -PlotPDFsOLE(pdf_1 = Glosea5PDF, pdf_2 = ECMWFPDF, legendPos = 'left') -PlotPDFsOLE(pdf_1 = Glosea5PDF, pdf_2 = MFPDF, legendPos = 'top') -PlotPDFsOLE(pdf_1 = ECMWFPDF, pdf_2 = MFPDF, legendSize = 1.2) } \author{ Eroteida Sanchez-Garcia - AEMET, //email{esanchezg@aemet.es} diff --git a/man/PlotTriangles4Categories.Rd b/man/PlotTriangles4Categories.Rd index 7329553c235056df4cd65cdd8794540943832f7e..8356da995e7813acb4de0bb3ac2392080b2054c9 100644 --- a/man/PlotTriangles4Categories.Rd +++ b/man/PlotTriangles4Categories.Rd @@ -33,7 +33,7 @@ PlotTriangles4Categories( ) } \arguments{ -\item{data}{array with three named dimensions: 'dimx', 'dimy', 'dimcat', +\item{data}{Array with three named dimensions: 'dimx', 'dimy', 'dimcat', containing the values to be displayed in a coloured image with triangles.} \item{brks}{A vector of the color bar intervals. The length must be one more @@ -45,17 +45,16 @@ default values.} \item{toptitle}{A string of the title of the grid. Set NULL as default.} -\item{sig_data}{logical array with the same dimensions as 'data' to add layers +\item{sig_data}{Logical array with the same dimensions as 'data' to add layers to the plot. A value of TRUE at a grid cell will draw a dot/symbol on the corresponding triangle of the plot. Set NULL as default.} -\item{pch_sig}{symbol to be used to represent sig_data. Takes 18 -(diamond) by default. See 'pch' in par() for additional -accepted options.} +\item{pch_sig}{Symbol to be used to represent sig_data. Takes 18 +(diamond) by default. See 'pch' in par() for additional accepted options.} -\item{col_sig}{colour of the symbol to represent sig_data.} +\item{col_sig}{Colour of the symbol to represent sig_data.} -\item{cex_sig}{parameter to increase/reduce the size of the symbols used +\item{cex_sig}{Parameter to increase/reduce the size of the symbols used to represent sig_data.} \item{xlab}{A logical value (TRUE) indicating if xlabels should be plotted} @@ -81,14 +80,16 @@ Set TRUE as default.} category (i.e. triangle). Set the sequence from 1 to the length of the categories (2 or 4).} -\item{cex_leg}{a number to indicate the increase/reductuion of the lab_legend used -to represent sig_data.} +\item{cex_leg}{A number to indicate the increase/reductuion of the lab_legend +used to represent sig_data.} -\item{col_leg}{color of the legend (triangles).} +\item{col_leg}{Color of the legend (triangles).} -\item{cex_axis}{a number to indicate the increase/reduction of the axis labels.} +\item{cex_axis}{A number to indicate the increase/reduction of the axis labels.} -\item{mar}{A numerical vector of the form c(bottom, left, top, right) which gives the number of lines of margin to be specified on the four sides of the plot.} +\item{mar}{A numerical vector of the form c(bottom, left, top, right) which +gives the number of lines of margin to be specified on the four sides of the +plot.} \item{fileout}{A string of full directory path and file name indicating where to save the plot. If not specified (default), a graphics device will pop up.} @@ -97,8 +98,9 @@ to save the plot. If not specified (default), a graphics device will pop up.} (file or window) to plot in. Set 'px' as default. See ?Devices and the creator function of the corresponding device.} -\item{res}{A positive number indicating resolution of the device (file or window) -to plot in. See ?Devices and the creator function of the corresponding device.} +\item{res}{A positive number indicating resolution of the device (file or +window) to plot in. See ?Devices and the creator function of the +corresponding device.} \item{figure.width}{a numeric value to control the width of the plot.} @@ -110,24 +112,23 @@ A figure in popup window by default, or saved to the specified path. } \description{ This function converts a 3-d numerical data array into a coloured -grid with triangles. It is useful for a slide or article to present tabular results as -colors instead of numbers. This can be used to compare the outputs of two or four categories ( -e.g. modes of variability, clusters, or forecast systems). +grid with triangles. It is useful for a slide or article to present tabular +results as colors instead of numbers. This can be used to compare the outputs +of two or four categories (e.g. modes of variability, clusters, or forecast +systems). } \examples{ -#Example with random data -arr1<- arr1<- array(runif(n = 12 * 7 * 4, min=-1, max=1),dim = c(12,7,4)) -names(dim(arr1)) <- c('dimx','dimy','dimcat') -arr2<- array(TRUE,dim = dim(arr1)) -arr2[which(arr1 < 0.3)] = FALSE +# Example with random data +arr1 <- array(runif(n = 4 * 5 * 4, min = -1, max = 1), dim = c(4,5,4)) +names(dim(arr1)) <- c('dimx', 'dimy', 'dimcat') +arr2 <- array(TRUE, dim = dim(arr1)) +arr2[which(arr1 < 0.3)] <- FALSE PlotTriangles4Categories(data = arr1, - cols = c('white','#fef0d9','#fdd49e','#fdbb84','#fc8d59', - '#e34a33','#b30000', '#7f0000'), - brks = c(-1, 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 1), - lab_legend = c('NAO+', 'BL','AR','NAO-'), - xtitle = "Target month", ytitle = "Lead time", - xlabels = c("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", - "Aug", "Sep", "Oct", "Nov", "Dec")) + cols = c('white','#fef0d9','#fdd49e','#fdbb84','#fc8d59'), + brks = c(-1, 0, 0.1, 0.2, 0.3, 0.4), + lab_legend = c('NAO+', 'BL','AR','NAO-'), + xtitle = "Target month", ytitle = "Lead time", + xlabels = c("Jan", "Feb", "Mar", "Apr")) } \author{ History:\cr diff --git a/man/Predictability.Rd b/man/Predictability.Rd index d37efcdcc4bf45c38ba5b4c175d919531e1e895f..3cc07a9af96f099cb5ead2d59d06e8891a83a33f 100644 --- a/man/Predictability.Rd +++ b/man/Predictability.Rd @@ -12,9 +12,10 @@ Predictability(dim, theta, ncores = NULL) the output of CST_ProxiesAttractor or ProxiesAttractor.} \item{theta}{An array of N named dimensions containing the inverse of the -persistence 'theta' as the output of CST_ProxiesAttractor or ProxiesAttractor.} +persistence 'theta' as the output of CST_ProxiesAttractor or +ProxiesAttractor.} -\item{ncores}{The number of cores to use in parallel computation} +\item{ncores}{The number of cores to use in parallel computation.} } \value{ A list of length 2: @@ -59,7 +60,7 @@ predyn <- Predictability(dim = attractor$dim, theta = attractor$theta) Faranda, D., Alvarez-Castro, M.C., Messori, G., Rodriguez, D., and Yiou, P. (2019). The hammam effect or how a warm ocean enhances large scale atmospheric predictability.Nature Communications, 10(1), 1316. -DOI = https://doi.org/10.1038/s41467-019-09305-8 " +DOI = \url{https://doi.org/10.1038/s41467-019-09305-8} " Faranda, D., Gabriele Messori and Pascal Yiou. (2017). Dynamical proxies of North Atlantic predictability and extremes. diff --git a/man/ProxiesAttractor.Rd b/man/ProxiesAttractor.Rd index 768ba7366482ed16390158a991bce22998cf0385..1cd883e30a588eea4767ef8bf1ceab104fc55aae 100644 --- a/man/ProxiesAttractor.Rd +++ b/man/ProxiesAttractor.Rd @@ -7,9 +7,12 @@ ProxiesAttractor(data, quanti, ncores = NULL) } \arguments{ -\item{data}{a multidimensional array with named dimensions to create the attractor. It requires a temporal dimension named 'time' and spatial dimensions called 'lat' and 'lon', or 'latitude' and 'longitude' or 'grid'.} +\item{data}{A multidimensional array with named dimensions to create the +attractor. It requires a temporal dimension named 'time' and spatial +dimensions called 'lat' and 'lon', or 'latitude' and 'longitude' or 'grid'.} -\item{quanti}{a number lower than 1 indicating the quantile to perform the computation of local dimension and theta} +\item{quanti}{A number lower than 1 indicating the quantile to perform the +computation of local dimension and theta} \item{ncores}{The number of cores to use in parallel computation.} } @@ -20,7 +23,7 @@ dim and theta This function computes two dinamical proxies of the attractor: The local dimension (d) and the inverse of the persistence (theta). These two parameters will be used as a condition for the computation of dynamical -scores to measure predictability and to compute bias correction conditioned by +scores to measure predictability and to compute bias correction conditioned by the dynamics with the function DynBiasCorrection. Funtion based on the matlab code (davide.faranda@lsce.ipsl.fr) used in: } @@ -35,16 +38,11 @@ time = c(1:length(Attractor$theta)) layout(matrix(c(1, 3, 2, 3), 2, 2)) plot(time, Attractor$dim, xlab = 'time', ylab = 'd', main = 'local dimension', type = 'l') -plot(time, Attractor$theta, xlab = 'time', ylab = 'theta', main = 'theta') -plot(Attractor$dim, Attractor$theta, col = 'blue', - main = "Proxies of the Attractor", - xlab = "local dimension", ylab = "theta", lwd = 8, 'p') - } \references{ Faranda, D., Alvarez-Castro, M.C., Messori, G., Rodriguez, D., and Yiou, P. (2019). The hammam effect or how a warm ocean enhances large scale atmospheric predictability. -Nature Communications, 10(1), 1316. DOI = https://doi.org/10.1038/s41467-019-09305-8 " +Nature Communications, 10(1), 1316. DOI = \url{https://doi.org/10.1038/s41467-019-09305-8} " Faranda, D., Gabriele Messori and Pascal Yiou. (2017). Dynamical proxies of North Atlantic predictability and extremes. diff --git a/man/QuantileMapping.Rd b/man/QuantileMapping.Rd index c251f33bff4f824a25d1a5457c2f5cef4534be61..804a1b50a09704882a005eb65bf8806b73a43dcf 100644 --- a/man/QuantileMapping.Rd +++ b/man/QuantileMapping.Rd @@ -41,8 +41,8 @@ samples have been stored. It can be NULL (default) in case all samples are used.} \item{method}{A character string indicating the method to be used: 'PTF', -'DIST','RQUANT','QUANT','SSPLIN'. By default, the empirical quantile mapping -'QUANT' is used.} +'DIST', 'RQUANT', 'QUANT', 'SSPLIN'. By default, the empirical quantile +mapping 'QUANT' is used.} \item{na.rm}{A logical value indicating if missing values should be removed (FALSE by default).} diff --git a/man/RFSlope.Rd b/man/RFSlope.Rd index 5c0c168955e9aef866a0e44c31b302e9e66756ca..88bf615dee10f8be8091ced1c99d4577c08f9a57 100644 --- a/man/RFSlope.Rd +++ b/man/RFSlope.Rd @@ -15,10 +15,10 @@ RFSlope( } \arguments{ \item{data}{Array containing the spatial precipitation fields to downscale. -The input array is expected to have at least two dimensions named "lon" and "lat" by default -(these default names can be changed with the \code{lon_dim} and \code{lat_dim} parameters) -and one or more dimensions over which to average the slopes, -which can be specified by parameter \code{time_dim}.} +The input array is expected to have at least two dimensions named "lon" and +"lat" by default (these default names can be changed with the \code{lon_dim} +and \code{lat_dim} parameters) and one or more dimensions over which to +average the slopes, which can be specified by parameter \code{time_dim}.} \item{kmin}{First wavenumber for spectral slope (default \code{kmin=1}).} @@ -33,7 +33,8 @@ with more than one element is chosen.} \item{lat_dim}{Name of lat dimension ("lat" by default).} -\item{ncores}{is an integer that indicates the number of cores for parallel computations using multiApply function. The default value is one.} +\item{ncores}{is an integer that indicates the number of cores for parallel +computations using multiApply function. The default value is one.} } \value{ RFSlope() returns spectral slopes using the RainFARM convention diff --git a/man/RFTemp.Rd b/man/RFTemp.Rd index 106ae6e218f2037ac5987d16e49641ac90c044d8..d16904dff58ce152294f521de8287c6b1a8c567a 100644 --- a/man/RFTemp.Rd +++ b/man/RFTemp.Rd @@ -26,57 +26,57 @@ RFTemp( ) } \arguments{ -\item{data}{Temperature array to downscale. -The input array is expected to have at least two dimensions named -"lon" and "lat" by default -(these default names can be changed with the \code{lon_dim} and -\code{lat_dim} parameters)} +\item{data}{Temperature array to downscale. The input array is expected to +have at least two dimensions named "lon" and "lat" by default (these default +names can be changed with the \code{lon_dim} and \code{lat_dim} parameters).} \item{lon}{Vector or array of longitudes.} \item{lat}{Vector or array of latitudes.} -\item{oro}{Array containing fine-scale orography (in m) -The destination downscaling area must be contained in the orography field.} +\item{oro}{Array containing fine-scale orography (in m). The destination +downscaling area must be contained in the orography field.} \item{lonoro}{Vector or array of longitudes corresponding to the fine orography.} \item{latoro}{Vector or array of latitudes corresponding to the fine orography.} -\item{xlim}{vector with longitude bounds for downscaling; -the full input field is downscaled if `xlim` and `ylim` are not specified.} +\item{xlim}{Vector with longitude bounds for downscaling; the full input field +is downscaled if `xlim` and `ylim` are not specified.} -\item{ylim}{vector with latitude bounds for downscaling} +\item{ylim}{Vector with latitude bounds for downscaling.} -\item{lapse}{float with environmental lapse rate} +\item{lapse}{Float with environmental lapse rate.} -\item{lon_dim}{string with name of longitude dimension} +\item{lon_dim}{String with name of longitude dimension.} -\item{lat_dim}{string with name of latitude dimension} +\item{lat_dim}{String with name of latitude dimension.} -\item{time_dim}{a vector of character string indicating the name of temporal dimension. By default, it is set to NULL and it considers "ftime", "sdate" and "time" as temporal dimensions.} +\item{time_dim}{A vector of character string indicating the name of temporal +dimension. By default, it is set to NULL and it considers "ftime", "sdate" +and "time" as temporal dimensions.} -\item{nolapse}{logical, if true `oro` is interpreted as a -fine-scale climatology and used directly for bias correction} +\item{nolapse}{Logical, if true `oro` is interpreted as a fine-scale +climatology and used directly for bias correction.} -\item{verbose}{logical if to print diagnostic output} +\item{verbose}{Logical if to print diagnostic output.} -\item{compute_delta}{logical if true returns only a delta to be used for +\item{compute_delta}{Logical if true returns only a delta to be used for out-of-sample forecasts.} -\item{method}{string indicating the method used for interpolation: +\item{method}{String indicating the method used for interpolation: "nearest" (nearest neighbours followed by smoothing with a circular uniform weights kernel), "bilinear" (bilinear interpolation) The two methods provide similar results, but nearest is slightly better provided that the fine-scale grid is correctly centered as a subdivision -of the large-scale grid} +of the large-scale grid.} -\item{delta}{matrix containing a delta to be applied to the downscaled +\item{delta}{Matrix containing a delta to be applied to the downscaled input data. The grid of this matrix is supposed to be same as that of -the required output field} +the required output field.} } \value{ -CST_RFTemp() returns a downscaled CSTools object +CST_RFTemp() returns a downscaled CSTools object. RFTemp() returns a list containing the fine-scale longitudes, latitudes and the downscaled fields. @@ -99,15 +99,15 @@ dim(o) <- c(lat = 29, lon = 29) lono <- seq(3, 10, 0.25) lato <- seq(41, 48, 0.25) res <- RFTemp(t, lon, lat, o, lono, lato, xlim = c(4, 8), ylim = c(43, 46), - lapse = 6.5) + lapse = 6.5) } \references{ Method described in ERA4CS MEDSCOPE milestone M3.2: -High-quality climate prediction data available to WP4 -[https://www.medscope-project.eu/the-project/deliverables-reports/]([https://www.medscope-project.eu/the-project/deliverables-reports/) +High-quality climate prediction data available to WP4 here: +\ url{https://www.medscope-project.eu/the-project/deliverables-reports/} and in H2020 ECOPOTENTIAL Deliverable No. 8.1: -High resolution (1-10 km) climate, land use and ocean change scenarios -[https://www.ecopotential-project.eu/images/ecopotential/documents/D8.1.pdf](https://www.ecopotential-project.eu/images/ecopotential/documents/D8.1.pdf) +High resolution (1-10 km) climate, land use and ocean change scenarios here: +\url{https://www.ecopotential-project.eu/images/ecopotential/documents/D8.1.pdf}. } \author{ Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} diff --git a/man/RF_Weights.Rd b/man/RF_Weights.Rd index 66e1ac5153c2a41605867e6cbbcd35c8b3120bd7..44b4d0359e4b2e8d54a0610971cc84931826c59c 100644 --- a/man/RF_Weights.Rd +++ b/man/RF_Weights.Rd @@ -18,45 +18,55 @@ RF_Weights( ) } \arguments{ -\item{zclim}{a multi-dimensional array with named dimension containing at least one precipiation field with spatial dimensions.} +\item{zclim}{A multi-dimensional array with named dimension containing at +least one precipiation field with spatial dimensions.} -\item{latin}{a vector indicating the latitudinal coordinates corresponding to the \code{zclim} parameter.} +\item{latin}{A vector indicating the latitudinal coordinates corresponding to +the \code{zclim} parameter.} -\item{lonin}{a vector indicating the longitudinal coordinates corresponding to the \code{zclim} parameter.} +\item{lonin}{A vector indicating the longitudinal coordinates corresponding to +the \code{zclim} parameter.} -\item{nf}{Refinement factor for downscaling (the output resolution is increased by this factor).} +\item{nf}{Refinement factor for downscaling (the output resolution is +increased by this factor).} -\item{lat}{Vector of latitudes. -The number of longitudes and latitudes is expected to be even and the same. If not -the function will perform a subsetting to ensure this condition.} +\item{lat}{Vector of latitudes. The number of longitudes and latitudes is +expected to be even and the same. If not the function will perform a +subsetting to ensure this condition.} \item{lon}{Vector of longitudes.} -\item{fsmooth}{Logical to use smooth conservation (default) or large-scale box-average conservation.} +\item{fsmooth}{Logical to use smooth conservation (default) or large-scale +box-average conservation.} -\item{lonname}{a character string indicating the name of the longitudinal dimension set as 'lon' by default.} +\item{lonname}{A character string indicating the name of the longitudinal +dimension set as 'lon' by default.} -\item{latname}{a character string indicating the name of the latitudinal dimension set as 'lat' by default.} +\item{latname}{A character string indicating the name of the latitudinal +dimension set as 'lat' by default.} -\item{ncores}{an integer that indicates the number of cores for parallel computations using multiApply function. The default value is one.} +\item{ncores}{An integer that indicates the number of cores for parallel +computations using multiApply function. The default value is one.} } \value{ -An object of class 's2dv_cube' containing in matrix \code{data} the weights with dimensions (lon, lat). +An object of class 's2dv_cube' containing in matrix \code{data} the +weights with dimensions (lon, lat). } \description{ -Compute climatological ("orographic") weights from a fine-scale precipitation climatology file. +Compute climatological ("orographic") weights from a fine-scale +precipitation climatology file. } \examples{ a <- array(1:2500, c(lat = 50, lon = 50)) res <- RF_Weights(a, seq(0.1 ,5, 0.1), seq(0.1 ,5, 0.1), - nf = 5, lat = 1:5, lon = 1:5) + nf = 5, lat = 1:5, lon = 1:5) } \references{ Terzago, S., Palazzi, E., & von Hardenberg, J. (2018). Stochastic downscaling of precipitation in complex orography: A simple method to reproduce a realistic fine-scale climatology. Natural Hazards and Earth System Sciences, 18(11), -2825-2840. http://doi.org/10.5194/nhess-18-2825-2018 . +2825-2840. \url{http://doi.org/10.5194/nhess-18-2825-2018}. } \author{ Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} diff --git a/man/RainFARM.Rd b/man/RainFARM.Rd index ef4485c94b1c290236206f97e2b0dcbc1ff06153..700ded13b100a74e847dbedb78418681face437e 100644 --- a/man/RainFARM.Rd +++ b/man/RainFARM.Rd @@ -24,66 +24,77 @@ RainFARM( ) } \arguments{ -\item{data}{Precipitation array to downscale. -The input array is expected to have at least two dimensions named "lon" and "lat" by default -(these default names can be changed with the \code{lon_dim} and \code{lat_dim} parameters) -and one or more dimensions over which to average these slopes, -which can be specified by parameter \code{time_dim}. -The number of longitudes and latitudes in the input data is expected to be even and the same. If not +\item{data}{Precipitation array to downscale. The input array is expected to +have at least two dimensions named "lon" and "lat" by default (these default +names can be changed with the \code{lon_dim} and \code{lat_dim} parameters) +and one or more dimensions over which to average these slopes, which can be +specified by parameter \code{time_dim}. The number of longitudes and +latitudes in the input data is expected to be even and the same. If not the function will perform a subsetting to ensure this condition.} \item{lon}{Vector or array of longitudes.} \item{lat}{Vector or array of latitudes.} -\item{nf}{Refinement factor for downscaling (the output resolution is increased by this factor).} +\item{nf}{Refinement factor for downscaling (the output resolution is +increased by this factor).} -\item{weights}{multi-dimensional array with climatological weights which can be obtained using -the \code{CST_RFWeights} function. If \code{weights=1.} (default) no weights are used. -The names of these dimensions must be at least 'lon' and 'lat'.} +\item{weights}{Multi-dimensional array with climatological weights which can +be obtained using the \code{CST_RFWeights} function. If \code{weights=1.} +(default) no weights are used. The names of these dimensions must be at +least 'lon' and 'lat'.} \item{nens}{Number of ensemble members to produce (default: \code{nens=1}).} \item{slope}{Prescribed spectral slope. The default is \code{slope=0.} -meaning that the slope is determined automatically over the dimensions specified by \code{time_dim}. A 1D array with named dimension can be provided (see details and examples)} +meaning that the slope is determined automatically over the dimensions +specified by \code{time_dim}. A 1D array with named dimension can be +provided (see details and examples).} \item{kmin}{First wavenumber for spectral slope (default: \code{kmin=1}).} -\item{fglob}{Logical to conseve global precipitation over the domain (default: FALSE)} +\item{fglob}{Logical to conseve global precipitation over the domain +(default: FALSE).} -\item{fsmooth}{Logical to conserve precipitation with a smoothing kernel (default: TRUE)} +\item{fsmooth}{Logical to conserve precipitation with a smoothing kernel +(default: TRUE).} -\item{nprocs}{The number of parallel processes to spawn for the use for parallel computation in multiple cores. (default: 1)} +\item{nprocs}{The number of parallel processes to spawn for the use for +parallel computation in multiple cores. (default: 1)} \item{time_dim}{String or character array with name(s) of time dimension(s) (e.g. "ftime", "sdate", "time" ...) over which to compute spectral slopes. If a character array of dimension names is provided, the spectral slopes will be computed over all elements belonging to those dimensions. -If omitted one of c("ftime", "sdate", "time") -is searched and the first one with more than one element is chosen.} +If omitted one of c("ftime", "sdate", "time") is searched and the first one +with more than one element is chosen.} \item{lon_dim}{Name of lon dimension ("lon" by default).} \item{lat_dim}{Name of lat dimension ("lat" by default).} -\item{drop_realization_dim}{Logical to remove the "realization" stochastic ensemble dimension (default: FALSE) - with the following behaviour if set to TRUE: - -1) if \code{nens==1}: the dimension is dropped; - -2) if \code{nens>1} and a "member" dimension exists: - the "realization" and "member" dimensions are compacted (multiplied) and the resulting dimension is named "member"; - -3) if \code{nens>1} and a "member" dimension does not exist: the "realization" dimension is renamed to "member".} +\item{drop_realization_dim}{Logical to remove the "realization" stochastic +ensemble dimension (default: FALSE) with the following behaviour if set to +TRUE: +\enumerate{ + \item{if \code{nens==1}: the dimension is dropped;} + \item{if \code{nens>1} and a "member" dimension exists: the "realization" + and "member" dimensions are compacted (multiplied) and the resulting + dimension is named "member";} + \item{if \code{nens>1} and a "member" dimension does not exist: the + "realization" dimension is renamed to "member".} +}} \item{verbose}{logical for verbose output (default: FALSE).} } \value{ -RainFARM() returns a list containing the fine-scale longitudes, latitudes -and the sequence of \code{nens} downscaled fields. -If \code{nens>1} an additional dimension named "realization" is added to the output array -after the "member" dimension (if it exists and unless \code{drop_realization_dim=TRUE} is specified). -The ordering of the remaining dimensions in the \code{exp} element of the input object is maintained. +RainFARM() Returns a list containing the fine-scale longitudes, + latitudes and the sequence of \code{nens} downscaled fields. If + \code{nens>1} an additional dimension named "realization" is added to the + output array after the "member" dimension (if it exists and unless + \code{drop_realization_dim=TRUE} is specified). The ordering of the + remaining dimensions in the \code{exp} element of the input object is + maintained. } \description{ This function implements the RainFARM stochastic precipitation downscaling method @@ -96,7 +107,10 @@ Terzago, S. et al. (2018). NHESS 18(11), 2825-2840. http://doi.org/10.5194/nhess D'Onofrio et al. (2014), J of Hydrometeorology 15, 830-843; Rebora et. al. (2006), JHM 7, 724. } \details{ -Wether parameter 'slope' and 'weights' presents seasonality dependency, a dimension name should match between these parameters and the input data in parameter 'data'. See example 2 below where weights and slope vary with 'sdate' dimension. +Wether parameter 'slope' and 'weights' presents seasonality +dependency, a dimension name should match between these parameters and the +input data in parameter 'data'. See example 2 below where weights and slope +vary with 'sdate' dimension. } \examples{ # Example for the 'reduced' RainFARM function @@ -110,29 +124,10 @@ lon_mat <- seq(10, 13.5, 0.5) # could also be a 2d matrix lat_mat <- seq(40, 43.5, 0.5) # Create a test array of weights ww <- array(1., dim = c(lon = 8 * nf, lat = 8 * nf)) -# or create proper weights using an external fine-scale climatology file -# Specify a weightsfn filename if you wish to save the weights -\dontrun{ -ww <- CST_RFWeights("./worldclim.nc", nf, lon = lon_mat, lat = lat_mat, - fsmooth = TRUE) -} # downscale using weights (ww=1. means do not use weights) res <- RainFARM(pr, lon_mat, lat_mat, nf, - fsmooth = TRUE, fglob = FALSE, - weights = ww, nens = 2, verbose = TRUE) -str(res) -#List of 3 -# $ data: num [1:3, 1:20, 1:64, 1:64] 0.186 0.212 0.138 3.748 0.679 ... -# $ lon : num [1:64] 9.78 9.84 9.91 9.97 10.03 ... -# $ lat : num [1:64] 39.8 39.8 39.9 40 40 ... -dim(res$data) -# lon lat ftime realization -# 64 64 20 2 -# Example 2: -slo <- array(c(0.1, 0.5, 0.7), c(sdate= 3)) -wei <- array(rnorm(8*8*3), c(lon = 8, lat = 8, sdate = 3)) -res <- RainFARM(lonlat_prec$data, lon = lonlat_prec$lon, - lat = lonlat_prec$lat, weights = wei, slope = slo, nf = 2) + fsmooth = TRUE, fglob = FALSE, + weights = ww, nens = 2, verbose = TRUE) } \author{ Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} diff --git a/man/RegimesAssign.Rd b/man/RegimesAssign.Rd index f66cfed15cc81928e0bb3209bbc3794e39b099dd..c11091f25ea00d86378b70c5552b897f2f51e5a8 100644 --- a/man/RegimesAssign.Rd +++ b/man/RegimesAssign.Rd @@ -16,34 +16,48 @@ RegimesAssign( ) } \arguments{ -\item{data}{an array containing anomalies with named dimensions: dataset, member, sdate, ftime, lat and lon.} +\item{data}{An array containing anomalies with named dimensions: dataset, +member, sdate, ftime, lat and lon.} -\item{ref_maps}{array with 3-dimensions ('lon', 'lat', 'cluster') containing the maps/clusters that will be used as a reference for the matching.} +\item{ref_maps}{Array with 3-dimensions ('lon', 'lat', 'cluster') containing +the maps/clusters that will be used as a reference for the matching.} -\item{lat}{a vector of latitudes corresponding to the positions provided in data and ref_maps.} +\item{lat}{A vector of latitudes corresponding to the positions provided in +data and ref_maps.} -\item{method}{whether the matching will be performed in terms of minimum distance (default = 'distance') or -the maximum spatial correlation (method = 'ACC') between the maps.} +\item{method}{Whether the matching will be performed in terms of minimum +distance (default = 'distance') or the maximum spatial correlation +(method = 'ACC') between the maps.} -\item{composite}{a logical parameter indicating if the composite maps are computed or not (default = FALSE).} +\item{composite}{A logical parameter indicating if the composite maps are +computed or not (default = FALSE).} -\item{memb}{a logical value indicating whether to compute composites for separate members (default FALSE) or as unique ensemble (TRUE). -This option is only available for when parameter 'composite' is set to TRUE and the data object has a dimension named 'member'.} +\item{memb}{A logical value indicating whether to compute composites for +separate members (default FALSE) or as unique ensemble (TRUE). This option +is only available for when parameter 'composite' is set to TRUE and the data +object has a dimension named 'member'.} -\item{ncores}{the number of multicore threads to use for parallel computation.} +\item{ncores}{The number of multicore threads to use for parallel computation.} } \value{ -A list with elements \code{$composite} (3-d array (lon, lat, k) containing the composites k=1,..,K for case (*1) - \code{$pvalue} ( array with the same structure as \code{$composite} containing the pvalue of the composites obtained through a t-test - that accounts for the serial dependence of the data with the same structure as Composite.) (only if composite='TRUE'), - \code{$cluster} (array with the same dimensions as data (except latitude and longitude which are removed) indicating the ref_maps to which each point is allocated.) , - \code{$frequency} (A vector of integers (from k = 1, ... k n reference maps) indicating the percentage of assignations corresponding to each map.), +A list with elements \code{$composite} (3-d array (lon, lat, k) +containing the composites k = 1,..,K for case (*1) or only k = 1 for any specific +cluster, i.e., case (*2)) (only if composite = 'TRUE'), \code{$pvalue} (array +with the same structure as \code{$composite} containing the pvalue of the +composites obtained through a t-test that accounts for the serial dependence +of the data with the same structure as Composite.) (only if composite='TRUE'), +\code{$cluster} (array with the same dimensions as data (except latitude and +longitude which are removed) indicating the ref_maps to which each point is +allocated.), \code{$frequency} (A vector of integers (from k = 1, ... k n +reference maps) indicating the percentage of assignations corresponding to +each map.), } \description{ -This function performs the matching between a field of anomalies and a set -of maps which will be used as a reference. The anomalies will be assigned to the reference map -for which the minimum Eucledian distance (method = 'distance') or highest spatial correlation -(method = 'ACC') is obtained. +This function performs the matching between a field of anomalies +and a set of maps which will be used as a reference. The anomalies will be +assigned to the reference map for which the minimum Eucledian distance +(method = 'distance') or highest spatial correlation (method = 'ACC') is +obtained. } \examples{ \dontrun{ @@ -54,7 +68,9 @@ res1 <- RegimesAssign(data = lonlat_temp$exp$data, ref_maps = drop(regimes), } } \references{ -Torralba, V. (2019) Seasonal climate prediction for the wind energy sector: methods and tools for the development of a climate service. Thesis. Available online: \url{https://eprints.ucm.es/56841/} +Torralba, V. (2019) Seasonal climate prediction for the wind +energy sector: methods and tools for the development of a climate service. +Thesis. Available online: \url{https://eprints.ucm.es/56841/} } \author{ Verónica Torralba - BSC, \email{veronica.torralba@bsc.es} diff --git a/man/SaveExp.Rd b/man/SaveExp.Rd index f1ace22c6e7b3a200883686b1531b5923e766ecb..3eb7705c146ca9d33e9b5f45397a3f405d577627 100644 --- a/man/SaveExp.Rd +++ b/man/SaveExp.Rd @@ -20,36 +20,49 @@ SaveExp( ) } \arguments{ -\item{data}{an multi-dimensional array with named dimensions (longitude, latitude, time, member, sdate)} +\item{data}{An multi-dimensional array with named dimensions (longitude, +latitude, time, member, sdate).} -\item{lon}{vector of logitud corresponding to the longitudinal dimension in data} +\item{lon}{Vector of logitud corresponding to the longitudinal dimension in +data.} -\item{lat}{vector of latitud corresponding to the latitudinal dimension in data} +\item{lat}{Vector of latitud corresponding to the latitudinal dimension in +data.} -\item{Dataset}{a vector of character string indicating the names of the datasets} +\item{Dataset}{A vector of character string indicating the names of the +datasets.} -\item{var_name}{a character string indicating the name of the variable to be saved} +\item{var_name}{A character string indicating the name of the variable to be +saved.} -\item{units}{a character string indicating the units of the variable} +\item{units}{A character string indicating the units of the variable.} -\item{startdates}{a vector of dates indicating the initialization date of each simulations} +\item{startdates}{A vector of dates indicating the initialization date of each +simulations.} -\item{Dates}{a matrix of dates with two dimension 'time' and 'sdate'.} +\item{Dates}{A matrix of dates with two dimension 'time' and 'sdate'.} -\item{cdo_grid_name}{a character string indicating the name of the grid e.g.: 'r360x181'} +\item{cdo_grid_name}{A character string indicating the name of the grid e.g.: +'r360x181'} -\item{projection}{a character string indicating the projection name} +\item{projection}{A character string indicating the projection name.} -\item{destination}{a character string indicating the path where to store the NetCDF files} +\item{destination}{A character string indicating the path where to store the +NetCDF files.} -\item{extra_string}{a character string to be include as part of the file name, for instance, to identify member or realization.} +\item{extra_string}{A character string to be include as part of the file name, +for instance, to identify member or realization.} } \value{ -the function creates as many files as sdates per dataset. Each file could contain multiple members. It would be added to the file name between underscore characters. -The path will be created with the name of the variable and each Datasets. +The function creates as many files as sdates per dataset. Each file +could contain multiple members. It would be added to the file name between +underscore characters. The path will be created with the name of the variable +and each Datasets. } \description{ -This function is created for compatibility with CST_Load/Load for saving post-processed datasets such as those calibrated of downscaled with CSTools functions +This function is created for compatibility with CST_Load/Load for +saving post-processed datasets such as those calibrated of downscaled with +CSTools functions } \examples{ \dontrun{ diff --git a/man/SplitDim.Rd b/man/SplitDim.Rd index a49043062c8e2dea743b9f391f53f9929bd41530..a0dc8bc69bc65b0e729491a0e27c132f2854ee76 100644 --- a/man/SplitDim.Rd +++ b/man/SplitDim.Rd @@ -13,21 +13,29 @@ SplitDim( ) } \arguments{ -\item{data}{an n-dimensional array with named dimensions} +\item{data}{An n-dimensional array with named dimensions.} -\item{split_dim}{a character string indicating the name of the dimension to split} +\item{split_dim}{A character string indicating the name of the dimension to +split.} -\item{indices}{a vector of numeric indices or dates} +\item{indices}{A vector of numeric indices or dates.} -\item{freq}{a character string indicating the frequency: by 'day', 'month' and 'year' or 'monthly' (by default). 'month' identifies months between 1 and 12 independetly of the year they belong to, while 'monthly' differenciates months from different years. Parameter 'freq' can also be numeric indicating the length in which to subset the dimension.} +\item{freq}{A character string indicating the frequency: by 'day', 'month' and +'year' or 'monthly' (by default). 'month' identifies months between 1 and 12 +independetly of the year they belong to, while 'monthly' differenciates +months from different years. Parameter 'freq' can also be numeric indicating +the length in which to subset the dimension.} -\item{new_dim_name}{a character string indicating the name of the new dimension.} +\item{new_dim_name}{A character string indicating the name of the new +dimension.} } \description{ -This function split a dimension in two. The user can select the dimension to split and provide indices indicating how to split that dimension or dates and the frequency expected (monthly or by day, month and year). The user can also provide a numeric frequency indicating the length of each division. +This function split a dimension in two. The user can select the +dimension to split and provide indices indicating how to split that dimension +or dates and the frequency expected (monthly or by day, month and year). The +user can also provide a numeric frequency indicating the length of each division. } \examples{ - data <- 1 : 20 dim(data) <- c(time = 10, lat = 2) indices <- c(rep(1,5), rep(2,5)) diff --git a/man/WeatherRegimes.Rd b/man/WeatherRegimes.Rd index 2f59b191133aede7e7da14153a942743e56907b4..68d67b76d60e45e2d0195bbcc11eafc888d84db3 100644 --- a/man/WeatherRegimes.Rd +++ b/man/WeatherRegimes.Rd @@ -19,60 +19,77 @@ WeatherRegime( ) } \arguments{ -\item{data}{an array containing anomalies with named dimensions with at least start date 'sdate', forecast time 'ftime', latitude 'lat' and longitude 'lon'.} +\item{data}{An array containing anomalies with named dimensions with at least +start date 'sdate', forecast time 'ftime', latitude 'lat' and longitude +'lon'.} -\item{ncenters}{Number of clusters to be calculated with the clustering function.} +\item{ncenters}{Number of clusters to be calculated with the clustering +function.} -\item{EOFs}{Whether to compute the EOFs (default = 'TRUE') or not (FALSE) to filter the data.} +\item{EOFs}{Whether to compute the EOFs (default = 'TRUE') or not (FALSE) to +filter the data.} -\item{neofs}{number of modes to be kept only if EOFs = TRUE has been selected. (default = 30).} +\item{neofs}{Number of modes to be kept only if EOFs = TRUE has been selected. +(default = 30).} -\item{varThreshold}{Value with the percentage of variance to be explained by the PCs. -Only sufficient PCs to explain this much variance will be used in the clustering.} +\item{varThreshold}{Value with the percentage of variance to be explained by +the PCs. Only sufficient PCs to explain this much variance will be used in +the clustering.} \item{lon}{Vector of longitudes.} \item{lat}{Vector of latitudes.} -\item{method}{Different options to estimate the clusters. The most traditional approach is the k-means analysis (default=’kmeans’) -but the function also support the different methods included in the hclust . These methods are: -"ward.D", "ward.D2", "single", "complete", "average" (= UPGMA), "mcquitty" (= WPGMA), "median" (= WPGMC) or "centroid" (= UPGMC). -For more details about these methods see the hclust function documentation included in the stats package.} +\item{method}{Different options to estimate the clusters. The most traditional +approach is the k-means analysis (default=’kmeans’) but the function also +support the different methods included in the hclust . These methods are: +"ward.D", "ward.D2", "single", "complete", "average" (= UPGMA), "mcquitty" +(= WPGMA), "median" (= WPGMC) or "centroid" (= UPGMC). For more details +about these methods see the hclust function documentation included in the +stats package.} -\item{iter.max}{Parameter to select the maximum number of iterations allowed (Only if method='kmeans' is selected).} +\item{iter.max}{Parameter to select the maximum number of iterations allowed +(Only if method = 'kmeans' is selected).} -\item{nstart}{Parameter for the cluster analysis determining how many random sets to choose (Only if method='kmeans' is selected).} +\item{nstart}{Parameter for the cluster analysis determining how many random +sets to choose (Only if method='kmeans' is selected).} \item{ncores}{The number of multicore threads to use for parallel computation.} } \value{ -A list with elements \code{$composite} (array with at least 3-d ('lat', 'lon', 'cluster') containing the composites k=1,..,K for case (*1) - \code{pvalue} (array with at least 3-d ('lat','lon','cluster') with the pvalue of the composites obtained through a t-test that accounts for the serial - \code{cluster} (A matrix or vector with integers (from 1:k) indicating the cluster to which each time step is allocated.), - \code{persistence} (Percentage of days in a month/season before a cluster is replaced for a new one (only if method=’kmeans’ has been selected.)), - \code{frequency} (Percentage of days in a month/season belonging to each cluster (only if method=’kmeans’ has been selected).), +A list with elements \code{$composite} (array with at least 3-d ('lat', +'lon', 'cluster') containing the composites k = 1,..,K for case (*1) or only k = 1 +for any specific cluster, i.e., case (*2)), \code{pvalue} (array with at least +3-d ('lat','lon','cluster') with the pvalue of the composites obtained through +a t-test that accounts for the serial dependence of the data with the same +structure as Composite.), \code{cluster} (A matrix or vector with integers +(from 1:k) indicating the cluster to which each time step is allocated.), +\code{persistence} (Percentage of days in a month/season before a cluster is +replaced for a new one (only if method=’kmeans’ has been selected.)), +\code{frequency} (Percentage of days in a month/season belonging to each +cluster (only if method=’kmeans’ has been selected).), } \description{ This function computes the weather regimes from a cluster analysis. -It can be applied over the dataset with dimensions -c(year/month, month/day, lon, lat), or by using PCs obtained from the application of the -EOFs analysis to filter the dataset. -The cluster analysis can be performed with the traditional k-means or those methods -included in the hclust (stats package). +It can be applied over the dataset with dimensions c(year/month, month/day, +lon, lat), or by using PCs obtained from the application of the EOFs analysis +to filter the dataset. The cluster analysis can be performed with the +traditional k-means or those methods included in the hclust (stats package). } \examples{ \dontrun{ res <- WeatherRegime(data = lonlat_temp$obs$data, lat = lonlat_temp$obs$lat, - EOFs = FALSE, ncenters = 4) + EOFs = FALSE, ncenters = 4) } } \references{ -Cortesi, N., V., Torralba, N., González-Reviriego, A., Soret, and F.J., Doblas-Reyes (2019). -Characterization of European wind speed variability using weather regimes. Climate Dynamics,53, -4961–4976, doi:10.1007/s00382-019-04839-5. +Cortesi, N., V., Torralba, N., González-Reviriego, A., Soret, and +F.J., Doblas-Reyes (2019). Characterization of European wind speed variability +using weather regimes. Climate Dynamics,53, 4961–4976, doi:10.1007/s00382-019-04839-5. -Torralba, V. (2019) Seasonal climate prediction for the wind energy sector: methods and tools -for the development of a climate service. Thesis. Available online: \url{https://eprints.ucm.es/56841/} +Torralba, V. (2019) Seasonal climate prediction for the wind +energy sector: methods and tools for the development of a climate service. +Thesis. Available online: \url{https://eprints.ucm.es/56841/} } \author{ Verónica Torralba - BSC, \email{veronica.torralba@bsc.es} diff --git a/man/training_analogs.Rd b/man/training_analogs.Rd index 447f8b0c27ea0f3a2b1c5feef79c75165a3dd1a2..2cf32e7b60be11f30ce4c5814cec9d4567146293 100644 --- a/man/training_analogs.Rd +++ b/man/training_analogs.Rd @@ -19,22 +19,25 @@ training_analogs( ) } \arguments{ -\item{pred}{List of matrix reanalysis data in a synoptic domain. The list -has to contain reanalysis atmospheric variables (instantaneous 12h data) -that must be indentify by parenthesis name. -For precipitation: -- u component of wind at 500 hPa (u500) in m/s -- v component of wind at 500 hPa (v500) in m/s -- temperature at 500 hPa (t500) in K -- temperature at 850 hPa (t850) in K -- temperature at 1000 hPa (t1000) in K -- geopotential height at 500 hPa (z500) in m -- geopotential height at 1000 hPa (z1000) in m -- sea level pressure (slp) in hPa -- specific humidity at 700 hPa (q700) in g/kg +\item{pred}{List of matrix reanalysis data in a synoptic domain. The list has +to contain reanalysis atmospheric variables (instantaneous 12h data) that +must be indentify by parenthesis name. For precipitation: +\itemize{ + \item{u component of wind at 500 hPa (u500) in m/s} + \item{v component of wind at 500 hPa (v500) in m/s} + \item{temperature at 500 hPa (t500) in K} + \item{temperature at 850 hPa (t850) in K} + \item{temperature at 1000 hPa (t1000) in K} + \item{geopotential height at 500 hPa (z500) in m} + \item{geopotential height at 1000 hPa (z1000) in m} + \item{sea level pressure (slp) in hPa} + \item{specific humidity at 700 hPa (q700) in g/kg} +} For maximum and minimum temperature: -- temperature at 1000 hPa (t1000) in K -- sea level pressure (slp) in hPa +\itemize{ + \item{temperature at 1000 hPa (t1000) in K} + \item{sea level pressure (slp) in hPa} +} All matrix must have [time,gridpoint] dimensions. (time = number of training days, gridpoint = number of synoptic gridpoints).} @@ -42,88 +45,111 @@ All matrix must have [time,gridpoint] dimensions. (instantaneous 12h data)(hPa). It has the same resolution as 'pred' parameter but with an extended domain. This domain contains extra degrees (most in the north and west part) compare to synoptic domain. The matrix must have -[time,gridpoint] dimensions. -(time = number of training days, gridpoint = number of extended gridpoints).} +[time,gridpoint] dimensions. (time = number of training days, +gridpoint = number of extended gridpoints).} \item{lon}{Vector of the synoptic longitude (from (-180º) to 180º), The vector must go from west to east.} -\item{lat}{Vector of the synoptic latitude. The vector must go from north to south.} +\item{lat}{Vector of the synoptic latitude. The vector must go from north to +south.} -\item{slp_lon}{Vector of the extended longitude (from (-180º) to 180º) +\item{slp_lon}{Vector of the extended longitude (from (-180º) to 180º). The vector must go from west to east.} -\item{slp_lat}{Vector of the extended latitude. The vector must go from north to south.} +\item{slp_lat}{Vector of the extended latitude. The vector must go from north +to south.} \item{var}{Variable name to downscale. There are two options: 'prec' for precipitation and 'temp' for maximum and minimum temperature.} \item{HR_path}{Local path of HR observational files (maestro and pcp/tmx-tmn). -For precipitation can be downloaded from http://www.aemet.es/documentos/es/serviciosclimaticos/cambio_climat/datos_diarios/dato_observacional/rejilla_5km/v2/Serie_AEMET_v2_pcp_1951a202006_txt.tar.gz -For maximum and minimum temperature can be downloaded from http://www.aemet.es/documentos/es/serviciosclimaticos/cambio_climat/datos_diarios/dato_observacional/rejilla_5km/temperatura/v1/tmax/Serie_AEMET_v1_tmax_1951a202006_txt.tar.gz and http://www.aemet.es/documentos/es/serviciosclimaticos/cambio_climat/datos_diarios/dato_observacional/rejilla_5km/temperatura/v1/tmin/Serie_AEMET_v1_tmin_1951a202006_txt.tar.gz respetively. -Maestro file (maestro_red_hr_SPAIN.txt) has gridpoint (nptos), longitude (lon), latitude (lat) and -altitude (alt) in columns (vector structure). -Data file (pcp/tmx/tmn_red_SPAIN_1951-201903.txt) includes 5km resolution spanish daily data -(precipitation or maximum and minimum temperature from january 1951 to june 2020. See README -file for more information. -IMPORTANT!: HR observational period must be the same as for reanalysis variables. -It is assumed that the training period is smaller than the HR original one (1951-2020), so it is -needed to make a new ascii file with the new period and the same structure as original, -specifying the training dates ('tdates' parameter) in the name -(e.g. 'pcp_red_SPAIN_19810101-19961231.txt' for '19810101-19961231' period).} +For precipitation and temperature can be downloaded from the following link: +\url{https://www.aemet.es/en/serviciosclimaticos/cambio_climat/datos_diarios?w=2} +respetively. Maestro file (maestro_red_hr_SPAIN.txt) has gridpoint (nptos), +longitude (lon), latitude (lat) and altitude (alt) in columns (vector +structure). Data file (pcp/tmx/tmn_red_SPAIN_1951-201903.txt) includes 5km +resolution spanish daily data (precipitation or maximum and minimum +temperature from january 1951 to june 2020. See README file for more +information. IMPORTANT!: HR observational period must be the same as for +reanalysis variables. It is assumed that the training period is smaller than +the HR original one (1951-2020), so it is needed to make a new ascii file +with the new period and the same structure as original, specifying the +training dates ('tdates' parameter) in the name (e.g. +'pcp_red_SPAIN_19810101-19961231.txt' for '19810101-19961231' period).} -\item{tdates}{Training period dates in format YYYYMMDD(start)-YYYYMMDD(end) (e.g. 19810101-19961231).} +\item{tdates}{Training period dates in format YYYYMMDD(start)-YYYYMMDD(end) +(e.g. 19810101-19961231).} } \value{ -matrix list (e.g. restrain) as a result of characterize the past synoptic -situations and the significant predictors needed to downscale seasonal forecast variables. -For precipitation the output includes: -um: u component of geostrophic wind in all period (numeric matrix with [time,gridpoint] dimensions) -vm: v component of geostrophic wind in all period (numeric matrix with [time,gridpoint] dimensions) -nger: number of synoptic situations (integer) -gu92: u component of geostrophic wind for each synoptic situation (numeric matrix with - [nger,gridpoint] dimensions) -gv92: v component of geostrophic wind for each synoptic situation (numeric matrix with - [nger,gridpoint] dimensions) -gu52: u component of wind at 500 hPa for each synotic situation (numeric matrix with - [nger,gridpoint] dimensions) -gv52: v component of wind at 500 hPa for each synotic situation (numeric matrix with - [nger,gridpoint] dimensions) -neni: number of reference centers where predictors are calculated (integer) -vdmin: minimum distances between each HR gridpoint and the four nearest synoptic - gridpoints (numeric matrix with [nptos,4] dimensions) (nptos = number of HR gridpoints) -vref: four nearest synoptic gridpoints to each HR gridpoint (integer matrix with - [nptos,4] dimensions) -ccm: multiple correlation coeficients (numeric matrix with [nger,nptos] dimensions) -indices: - - lab_pred: numeric labels of selected predictors (integer matrix - with [nger,nptos,11,1] dimensions) - - cor_pred: partial correlation of selected predictors (numeric matrix with - [nger,nptos,11,2] dimensions) +A matrix list (e.g. restrain) as a result of characterize the past +synoptic situations and the significant predictors needed to downscale +seasonal forecast variables. For precipitation the output includes: +\itemize{ + \item{'um': u component of geostrophic wind in all period (numeric matrix + with [time, gridpoint] dimensions).} + \item{'vm': v component of geostrophic wind in all period (numeric matrix + with [time,gridpoint] dimensions).} + \item{'nger': number of synoptic situations (integer).} + \item{'gu92': u component of geostrophic wind for each synoptic situation + (numeric matrix with [nger,gridpoint] dimensions).} + \item{'gv92': v component of geostrophic wind for each synoptic situation + (numeric matrix with [nger, gridpoint] dimensions).} + \item{'gu52': u component of wind at 500 hPa for each synotic situation + (numeric matrix with [nger, gridpoint] dimensions).} + \item{'gv52': v component of wind at 500 hPa for each synotic situation + (numeric matrix with [nger, gridpoint] dimensions).} + \item{'neni': number of reference centers where predictors are calculated + (integer).} + \item{'vdmin': minimum distances between each HR gridpoint and the four + nearest synoptic gridpoints (numeric matrix with [nptos,4] dimensions) + (nptos = number of HR gridpoints).} + \item{'vref': four nearest synoptic gridpoints to each HR gridpoint (integer + matrix with [nptos, 4] dimensions).} + \item{'ccm': multiple correlation coeficients (numeric matrix with [nger, nptos] + dimensions) indices: + \itemize{ + \item{'lab_pred': numeric labels of selected predictors (integer matrix + with [nger,nptos,11,1] dimensions).} + \item{'cor_pred': partial correlation of selected predictors (numeric + matrix with [nger,nptos,11,2] dimensions).} + } + } +} For maximum and minimum temperature the output includes: -um: u component of geostrophic wind in all training period (numeric matrix with [time,gridpoint] dimensions) -vm: v component of geostrophic wind in all training period (numeric matrix with [time,gridpoint] dimensions) -insol: insolation in all training period (numeric vector with [time] dimension) -neni: number of reference centers where predictors are calculated (integer) -vdmin: minimum distances between each HR gridpoint and the four nearest synoptic - gridpoints (numeric matrix with [nptos,4] dimensions) (nptos = number of HR gridpoints) -vref: four nearest synoptic gridpoints to each HR gridpoint (integer matrix with - [nptos,4] dimensions) - +\itemize{ + \item{'um': u component of geostrophic wind in all training period (numeric + matrix with [time,gridpoint] dimensions).} + \item{'vm': v component of geostrophic wind in all training period (numeric + matrix with [time,gridpoint] dimensions).} + \item{'insol': insolation in all training period (numeric vector with [time] + dimension).} + \item{'neni': number of reference centers where predictors are calculated + (integer).} + \item{'vdmin': minimum distances between each HR gridpoint and the four + nearest synoptic gridpoints (numeric matrix with [nptos,4] dimensions) + (nptos = number of HR gridpoints).} + \item{'vref': four nearest synoptic gridpoints to each HR gridpoint (integer + matrix with [nptos,4] dimensions).} +} The output can directly use as argument to 'CST_AnalogsPredictors' function -(e.g. resdowns <- CST_AnalogsPredictors(...,restrain)) +(e.g. resdowns <- CST_AnalogsPredictors(...,restrain)). } \description{ -This function caracterizes the synoptic situations in a past period based on -low resolution reanalysis data (e.g, ERAInterim 1.5º x 1.5º) and an observational high -resolution (HR) dataset (AEMET 5 km gridded daily precipitation and maximum and -minimum temperature) (Peral et al., 2017)). -The method uses three domains: -- peninsular Spain and Balearic Islands domain (5 km resolution): HR domain -- synoptic domain (low resolution): it should be centered over Iberian Peninsula and - cover enough extension to detect as much synoptic situations as possible. -- extended domain (low resolution): it is an extension of the synoptic - domain. It is used for 'slp_ext' parameter (see 'slp_lon' and 'slp_lat' below). +This function caracterizes the synoptic situations in a past +period based on low resolution reanalysis data (e.g, ERAInterim 1.5º x 1.5º) +and an observational high resolution (HR) dataset (AEMET 5 km gridded daily +precipitation and maximum and minimum temperature) (Peral et al., 2017)). +The method uses three domains: +\itemize{ + \item{peninsular Spain and Balearic Islands domain (5 km resolution): HR domain} + \item{synoptic domain (low resolution): it should be centered over Iberian + Peninsula and cover enough extension to detect as much synoptic + situations as possible.} + \item{extended domain (low resolution): it is an extension of the synoptic + domain. It is used for 'slp_ext' parameter (see 'slp_lon' and 'slp_lat' + below).} +} } \author{ Marta Dominguez Alonso - AEMET, \email{mdomingueza@aemet.es} diff --git a/tests/testthat/test-CST_BiasCorrection.R b/tests/testthat/test-CST_BiasCorrection.R index 826fcf127806fb77413e7d5cd7e78c49d7c09359..f16592532646ccd4068f8bd047fd2cd61ed507ad 100644 --- a/tests/testthat/test-CST_BiasCorrection.R +++ b/tests/testthat/test-CST_BiasCorrection.R @@ -51,7 +51,7 @@ obs4_1[1,1,1,1] <- NA ############################################## -test_that("1. Inpput checks", { +test_that("1. Input checks", { # s2dv_cube expect_error( CST_BiasCorrection(exp = 1), diff --git a/tests/testthat/test-CST_Calibration.R b/tests/testthat/test-CST_Calibration.R index e832a539e3d26a3f2ee936ab4f0aed5f50bd3b1e..8a14acd9704b8f6ddea9fc4dfed23bf2a238a413 100644 --- a/tests/testthat/test-CST_Calibration.R +++ b/tests/testthat/test-CST_Calibration.R @@ -1,5 +1,25 @@ -context("Generic tests") -test_that("Sanity checks", { +context("CSTools::CST_Calibration tests") + +############################################## +# dat1 +exp_obs <- lonlat_temp +exp <- exp_obs[[1]] +obs <- exp_obs[[2]] +exp$data <- ClimProjDiags::Subset(exp_obs[[1]]$data, c('member', 'lon', 'lat'), list(1:2, 1:4, 1:4)) +obs$data <- ClimProjDiags::Subset(exp_obs[[2]]$data, c('lon', 'lat'), list(1:4, 1:4)) +exp$lon <- exp$lon[1:4] +exp$lat <- exp$lat[1:4] +obs$lon <- obs$lon[1:4] +obs$lat <- obs$lat[1:4] + +# dat2 +exp2 <- exp +exp2$data[1, 2, 1, 1, 1, 1] <- NA +obs2 <- obs +obs2$data[1, 1, 2, 1, 1, 1] <- NA +############################################## + +test_that("1. Input checks", { expect_error( CST_Calibration(exp = 1), "Parameter 'exp' and 'obs' must be of the class 's2dv_cube', " @@ -8,36 +28,43 @@ test_that("Sanity checks", { CST_Calibration(obs = 1), c("argument \"exp\" is missing, with no default") ) - library(zeallot) - c(exp, obs) %<-% lonlat_temp cal <- CST_Calibration(exp = exp, obs = obs) - expect_equal(length(cal), 9) - expect_equal(as.numeric(dim(cal$data)), as.numeric(dim(exp$data))) - expect_equal(cal$lat, exp$lat) - expect_equal(cal$lat, obs$lat) - expect_equal(cal$lon, exp$lon) - expect_equal(cal$lon, obs$lon) - # expect_error( - # CST_Calibration(exp = exp, obs = exp), - # "The length of the dimension 'member' in the component 'data' " - # ) - - exp2 <- exp - exp2$data[1, 2, 1, 1, 1, 1] <- NA + expect_equal( + length(cal), + 9 + ) + expect_equal( + as.numeric(dim(cal$data)), + as.numeric(dim(exp$data)) + ) + expect_equal( + cal$lat, + exp$lat + ) + expect_equal( + cal$lat, + obs$lat + ) + expect_equal( + cal$lon, + exp$lon + ) + expect_equal( + cal$lon, + obs$lon + ) expect_warning( CST_Calibration(exp = exp2, obs = obs), "Parameter 'exp' contains NA values." ) - - obs2 <- obs - obs2$data[1, 1, 2, 1, 1, 1] <- NA expect_warning( CST_Calibration(exp = exp, obs = obs2), "Parameter 'obs' contains NA values." ) - expect_warning( CST_Calibration(exp = exp2, obs = obs2), "Parameter 'obs' contains NA values", "Parameter 'exp' contains NA values." ) -}) +}) + +############################################## diff --git a/tests/testthat/test-CST_CategoricalEnsCombination.R b/tests/testthat/test-CST_CategoricalEnsCombination.R index 1e366bf33cc9858c3efc482ba70e5fe24f9c25bd..fad6cff0a573238064a189d4341fef065c264fd9 100644 --- a/tests/testthat/test-CST_CategoricalEnsCombination.R +++ b/tests/testthat/test-CST_CategoricalEnsCombination.R @@ -1,4 +1,25 @@ -context("Generic tests") +context("CSTools::CST_CategoricalEnsCombination tests") + +############################################## +# dat1 +exp_obs <- lonlat_temp +exp <- exp_obs[[1]] +obs <- exp_obs[[2]] +exp$data <- ClimProjDiags::Subset(exp_obs[[1]]$data, c('member', 'lon', 'lat'), list(1:4, 1:4, 1:4)) +obs$data <- ClimProjDiags::Subset(exp_obs[[2]]$data, c('lon', 'lat'), list(1:4, 1:4)) +exp$lon <- exp$lon[1:4] +exp$lat <- exp$lat[1:4] +obs$lon <- obs$lon[1:4] +obs$lat <- obs$lat[1:4] + +# dat2 +exp2 <- exp +exp2$data[1, 2, 1, 1, 1, 1] <- NA +obs2 <- obs +obs2$data[1, 1, 2, 1, 1, 1] <- NA + +############################################## + test_that("Sanity checks", { expect_error( CST_CategoricalEnsCombination(exp = 1), @@ -8,40 +29,55 @@ test_that("Sanity checks", { CST_CategoricalEnsCombination(obs = 1), c("argument \"exp\" is missing, with no default") ) - library(zeallot) - c(exp, obs) %<-% lonlat_temp cal <- CST_CategoricalEnsCombination(exp = exp, obs = obs) - expect_equal(length(cal), 9) - expect_equal(as.numeric(dim(cal$data)[c(1, 2)]), c(1, 1)) - expect_equal(as.numeric(dim(cal$data)[c(-1, -2, -3)]), - as.numeric(dim(exp$data)[c(-1, -2)])) - expect_equal(names(dim(cal$data))[c(-1, -2, -3)], - names(dim(exp$data))[c(-1, -2)]) - expect_equal(names(dim(cal$data))[c(1, 2, 3)], - c("dataset", "member", "category")) - expect_equal(cal$lat, exp$lat) - expect_equal(cal$lat, obs$lat) - expect_equal(cal$lon, exp$lon) - expect_equal(cal$lon, obs$lon) + expect_equal( + length(cal), + 9 + ) + expect_equal( + as.numeric(dim(cal$data)[c(1, 2)]), + c(1, 1) + ) + expect_equal( + as.numeric(dim(cal$data)[c(-1, -2, -3)]), + as.numeric(dim(exp$data)[c(-1, -2)]) + ) + expect_equal( + names(dim(cal$data))[c(-1, -2, -3)], + names(dim(exp$data))[c(-1, -2)] + ) + expect_equal( + names(dim(cal$data))[c(1, 2, 3)], + c("dataset", "member", "category") + ) + expect_equal( + cal$lat, + exp$lat + ) + expect_equal( + cal$lat, + obs$lat + ) + expect_equal( + cal$lon, + exp$lon + ) + expect_equal( + cal$lon, + obs$lon + ) expect_error( CST_CategoricalEnsCombination(exp = exp, obs = exp), "The length of the dimension 'member' in the component 'data' " ) - - exp2 <- exp - exp2$data[1, 2, 1, 1, 1, 1] <- NA expect_warning( CST_CategoricalEnsCombination(exp = exp2, obs = obs), "Parameter 'exp' contains NA values." ) - - obs2 <- obs - obs2$data[1, 1, 2, 1, 1, 1] <- NA expect_warning( CST_CategoricalEnsCombination(exp = exp, obs = obs2), "Parameter 'obs' contains NA values." ) - expect_warning( CST_CategoricalEnsCombination(exp = exp2, obs = obs2), "Parameter 'obs' contains NA values", "Parameter 'exp' contains NA values." diff --git a/tests/testthat/test-CST_EnsClustering.R b/tests/testthat/test-CST_EnsClustering.R index 2e7364d9b7e5c7e44af6b53eacf60210f5193e11..104b8ecde8310ae8647f57ef402820b64d16008f 100644 --- a/tests/testthat/test-CST_EnsClustering.R +++ b/tests/testthat/test-CST_EnsClustering.R @@ -1,52 +1,82 @@ context("Generic tests") -test_that("Sanity and Functionality tests", { - data <- rnorm(2 * 15 * 4 * 5 * 6 * 7) - dim(data) <- c(dataset = 2, member = 15, - sdate = 4, ftime = 5, lat = 6, lon = 7) - lon <- seq(0, 12, 2) - lat <- seq(10, 15, 1) - exp <- list(data = data, lat = lat, lon = lon) +############################################## +# dat1 +data <- rnorm(2 * 10 * 4 * 5 * 6 * 7) +dim(data) <- c(dataset = 2, member = 10, + sdate = 4, ftime = 5, lat = 6, lon = 7) +lon <- seq(0, 12, 2) +lat <- seq(10, 15, 1) +exp <- list(data = data, lat = lat, lon = lon) +attr(exp, "class") <- "s2dv_cube" +############################################## +test_that("1. Input checks", { # Check error messages expect_error( - CST_EnsClustering(exp), + CST_EnsClustering(rnorm(2 * 15 * 4 * 5 * 6 * 7)), "Parameter 'exp' must be of the class 's2dv_cube'" ) - attr(exp, "class") <- "s2dv_cube" - expect_error( CST_EnsClustering(exp, time_moment = "invalid"), "Invalid time_moment" ) - exp$lat <- 1 - expect_error(CST_EnsClustering(exp), "Incorrect lat length") + expect_error( + CST_EnsClustering(exp), + "Incorrect lat length" + ) exp$lon <- 1 exp$lat <- lat - expect_error(CST_EnsClustering(exp), "Incorrect lon length") + expect_error( + CST_EnsClustering(exp), + "Incorrect lon length" + ) exp$lon <- lon +}) +test_that("2. Output checks", { # Sanity checks on dimensions res <- CST_EnsClustering(exp, numclus = 3) - expect_equivalent(dim(res$cluster), dim(exp$data)[c(2, 1, 3)]) + expect_equal( + dim(res$cluster), + dim(exp$data)[c(2, 1, 3)] + ) res <- CST_EnsClustering(exp, numclus = 3, cluster_dim = "sdate") - expect_equivalent(dim(res$cluster), dim(exp$data)[c(3, 1, 2)]) + expect_equal( + dim(res$cluster), + dim(exp$data)[c(3, 1, 2)] + ) res <- CST_EnsClustering(exp, numclus = 3, - cluster_dim = c("member", "dataset", "sdate")) - expect_equivalent(dim(res$cluster), dim(exp$data)[c(2, 1, 3)]) + cluster_dim = c("member", "dataset", "sdate")) + expect_equal( + dim(res$cluster), + dim(exp$data)[c(2, 1, 3)] + ) res <- CST_EnsClustering(exp, numclus = 3, cluster_dim = c("member", "sdate")) - expect_equivalent(dim(res$cluster), dim(exp$data)[c(2, 3, 1)]) - expect_equivalent(dim(res$freq), c(cluster = 3, dim(exp$data)[1])) - expect_equivalent(dim(res$closest_member$sdate), c(cluster = 3, - dim(exp$data)[1])) - expect_equivalent(dim(res$repr_field), c(cluster = 3, - dim(exp$data)[c(5, 6)], dim(exp$data)[1])) - expect_equivalent(dim(res$composites), c(cluster = 3, - dim(exp$data)[c(5, 6)], dim(exp$data)[1])) + expect_equal( + dim(res$cluster), + dim(exp$data)[c(2, 3, 1)] + ) + expect_equal( + dim(res$freq), + c(cluster = 3, dim(exp$data)[1]) + ) + expect_equal( + dim(res$closest_member$sdate), + c(cluster = 3, dim(exp$data)[1]) + ) + expect_equal( + dim(res$repr_field), + c(cluster = 3, dim(exp$data)[c(5, 6)], dim(exp$data)[1]) + ) + expect_equal( + dim(res$composites), + c(cluster = 3, dim(exp$data)[c(5, 6)], dim(exp$data)[1]) + ) # Functionality tests res <- CST_EnsClustering(exp, numclus = 3, variance_explained = 80, - cluster_dim = "member") + cluster_dim = "member") # The closest member of each cluster should be member of that cluster for (i in 1:3) { expect_equivalent(res$cluster[res$closest_member$member[i, 1, 1], 1, 1], i) diff --git a/tests/testthat/test-CST_RFTemp.R b/tests/testthat/test-CST_RFTemp.R index 536e44f0e0092d0266cf253271c5df6138c7666e..581e04a3535972a8d2c0f9268d448d2b348d3f8a 100644 --- a/tests/testthat/test-CST_RFTemp.R +++ b/tests/testthat/test-CST_RFTemp.R @@ -1,4 +1,7 @@ -context("Generic tests") +context("CSTools::CST_RFTemp tests") + +############################################## + test_that("Sanity checks and simple use cases", { # Generate simple synthetic data t <- rnorm(2 * 6 * 6 * 2 * 3 * 4) * 10 + 273.15 + 10 @@ -14,13 +17,13 @@ test_that("Sanity checks and simple use cases", { attr(oro, "class") <- "s2dv_cube" expect_error( - res <- CST_RFTemp(exp, oro, xlim = c(1, 3), ylim = c(1, 3)), + res <- CST_RFTemp(exp, oro, xlim = c(1, 3), ylim = c(1, 3), time_dim = 'ftime'), paste("Parameter 'data' must be of the class", "'s2dv_cube', as output by CSTools::CST_Load.")) attr(exp, "class") <- "s2dv_cube" expect_error( - res <- CST_RFTemp(exp, oro, xlim = c(1, 3), ylim = c(1, 3)), + res <- CST_RFTemp(exp, oro, xlim = c(1, 3), ylim = c(1, 3), time_dim = 'ftime'), "Orography not available for selected area" ) @@ -28,7 +31,7 @@ test_that("Sanity checks and simple use cases", { oro$lat <- oro$lat + 60 expect_error( - res <- CST_RFTemp(exp, oro, xlim = c(3, 8), ylim = c(43, 46)), + res <- CST_RFTemp(exp, oro, xlim = c(3, 8), ylim = c(43, 46), time_dim = 'ftime'), "Downscaling area not contained in input data" )