From 92bf83aad270bb4c20f5c21566c60203f17fca4e Mon Sep 17 00:00:00 2001 From: Bert Van schaeybroeck Date: Mon, 9 Dec 2019 09:49:53 +0100 Subject: [PATCH 1/4] Handling of case of insufficient data, following the comment of Deborah Verfaillie. The function now warns (and does no calibration) when 3 or less observation-model pairs are available for training. A new parameter na.fill has been introduced. --- DESCRIPTION | 2 +- R/CST_Calibration.R | 43 ++++++++++++++++++++++++---- man/Analogs.Rd | 13 ++++----- man/BEI_PDFBest.Rd | 7 ++--- man/BEI_Weights.Rd | 7 ++--- man/CST_Analogs.Rd | 9 +++--- man/CST_Anomaly.Rd | 7 ++--- man/CST_BEI_Weighting.Rd | 7 ++--- man/CST_BiasCorrection.Rd | 7 ++--- man/CST_Calibration.Rd | 15 +++++----- man/CST_CategoricalEnsCombination.Rd | 7 ++--- man/CST_EnsClustering.Rd | 1 - man/CST_Load.Rd | 1 - man/CST_MultiEOF.Rd | 5 ++-- man/CST_MultiMetric.Rd | 9 +++--- man/CST_MultivarRMSE.Rd | 7 ++--- man/CST_QuantileMapping.Rd | 7 ++--- man/CST_RFSlope.Rd | 1 - man/CST_RFWeights.Rd | 7 ++--- man/CST_RainFARM.Rd | 7 ++--- man/CST_SaveExp.Rd | 7 ++--- man/CST_SplitDim.Rd | 4 +-- man/EnsClustering.Rd | 1 - man/MultiEOF.Rd | 1 - man/PlotCombinedMap.Rd | 15 +++++----- man/PlotForecastPDF.Rd | 10 +++---- man/PlotMostLikelyQuantileMap.Rd | 7 ++--- man/RFSlope.Rd | 1 - man/RainFARM.Rd | 9 +++--- man/SplitDim.Rd | 1 - man/areave_data.Rd | 1 - man/as.s2dv_cube.Rd | 7 ++--- man/lonlat_data.Rd | 1 - man/lonlat_prec.Rd | 1 - man/s2dv_cube.Rd | 7 ++--- 35 files changed, 122 insertions(+), 120 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 0e47736a..c3de9d84 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -70,4 +70,4 @@ VignetteBuilder: knitr License: Apache License 2.0 Encoding: UTF-8 LazyData: true -RoxygenNote: 5.0.0 +RoxygenNote: 6.1.1 diff --git a/R/CST_Calibration.R b/R/CST_Calibration.R index 1cd9bab4..efc7eeaa 100644 --- a/R/CST_Calibration.R +++ b/R/CST_Calibration.R @@ -13,6 +13,7 @@ #'@param cal.method is the calibration method used, can be either \code{bias}, \code{evmos}, \code{mse_min} or \code{crps_min}. 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. #'@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. #'@return an object of class \code{s2dv_cube} containing the calibrated forecasts in the element \code{$data} with the same dimensions of the experimental data. #' #'@import s2dverification @@ -37,8 +38,8 @@ #'str(a) #'@export - -CST_Calibration <- function(exp, obs, cal.method = "mse_min", eval.method = "leave-one-out", multi.model = F) { +CST_Calibration <- function(exp, obs, cal.method = "mse_min", + eval.method = "leave-one-out", multi.model = F, na.fill = T) { if (!inherits(exp, "s2dv_cube") || !inherits(obs, "s2dv_cube")) { stop("Parameter 'exp' and 'obs' must be of the class 's2dv_cube', ", "as output by CSTools::CST_Load.") @@ -54,7 +55,7 @@ CST_Calibration <- function(exp, obs, cal.method = "mse_min", eval.method = "lea } exp$data <- .calibration.wrap(exp = exp$data, obs = obs$data, cal.method = cal.method, eval.method = eval.method, - multi.model = multi.model) + multi.model = multi.model, na.fill = na.fill) exp$Datasets <- c(exp$Datasets, obs$Datasets) exp$source_files <- c(exp$source_files, obs$source_files) @@ -62,7 +63,15 @@ CST_Calibration <- function(exp, obs, cal.method = "mse_min", eval.method = "lea } -.calibration.wrap <- function(exp, obs, cal.method, eval.method, multi.model) { +.data.set.sufficiently.large <- function(mod, obs){ + amt.min.samples <- 3 + amt.good.pts <- sum(!is.na(obs) & !apply(mod, c(2), function(x) all(is.na(x)))) + return(amt.good.pts > amt.min.samples) +} + + +.calibration.wrap <- function(exp, obs, cal.method, + eval.method, multi.model, na.fill) { dim.exp <- dim(exp) amt.dims.exp <- length(dim.exp) @@ -95,11 +104,24 @@ CST_Calibration <- function(exp, obs, cal.method = "mse_min", eval.method = "lea } obs <- Subset(obs, along = "member", indices = 1, drop = "selected") + + data.set.sufficiently.large.out <- Apply(data = list(mod = exp, obs = obs), + target_dims = list(mod = target.dim.names.exp, obs = target.dim.names.obs), + fun = .data.set.sufficiently.large)$output1 + + if(!all(data.set.sufficiently.large.out)){ + if(na.fill){ + warning("Some forecast data could not be corrected due to data lack and is replaced with NA values") + } else { + warning("Some forecast data could not be corrected due to data lack and is replaced with uncorrected values") + } + } calibrated <- Apply(data = list(mod = exp, obs = obs), cal.method = cal.method, eval.method = eval.method, multi.model = multi.model, + na.fill = na.fill, target_dims = list(mod = target.dim.names.exp, obs = target.dim.names.obs), fun = .cal)$output1 @@ -122,7 +144,7 @@ CST_Calibration <- function(exp, obs, cal.method = "mse_min", eval.method = "lea return(dexes.lst) } -.cal <- function(mod, obs, cal.method, eval.method, multi.model) { +.cal <- function(mod, obs, cal.method, eval.method, multi.model, na.fill) { var.obs <- as.vector(obs) var.fc <- mod @@ -130,6 +152,16 @@ CST_Calibration <- function(exp, obs, cal.method = "mse_min", eval.method = "lea amt.mbr <- dims.fc[1] amt.sdate <- dims.fc[2] var.cor.fc <- NA * var.fc + names(dim(var.cor.fc)) <- c("member", "sdate") + + if(!.data.set.sufficiently.large(mod = mod, obs = obs)){ + if(na.fill){ + return(var.cor.fc) + } else { + var.cor.fc[] <- var.fc[] + return(var.cor.fc) + } + } eval.train.dexeses <- .make.eval.train.dexes(eval.method, amt.points = amt.sdate) amt.resamples <- length(eval.train.dexeses) @@ -175,7 +207,6 @@ CST_Calibration <- function(exp, obs, cal.method = "mse_min", eval.method = "lea stop("unknown calibration method: ",cal.method) } } - names(dim(var.cor.fc)) <- c("member", "sdate") return(var.cor.fc) } diff --git a/man/Analogs.Rd b/man/Analogs.Rd index ee8a737e..52d9ff97 100644 --- a/man/Analogs.Rd +++ b/man/Analogs.Rd @@ -5,8 +5,8 @@ \title{Analogs based on large scale fields.} \usage{ Analogs(expL, obsL, time_obsL, expVar = NULL, obsVar = NULL, - criteria = "Large_dist", lonVar = NULL, latVar = NULL, region = NULL, - nAnalogs = NULL, return_list = FALSE) + criteria = "Large_dist", lonVar = NULL, latVar = NULL, + region = NULL, nAnalogs = NULL, return_list = FALSE) } \arguments{ \item{expL}{an array of N named dimensions containing the experimental field @@ -377,11 +377,6 @@ Local_scalecor <- Analogs(expL=expSLP, str(Local_scalecor) Local_scalecor$AnalogsInfo -} -\author{ -M. Carmen Alvarez-Castro, \email{carmen.alvarez-castro@cmcc.it} - -Nuria Perez-Zanon \email{nuria.perez@bsc.es} } \references{ Yiou, P., T. Salameh, P. Drobinski, L. Menut, R. Vautard, @@ -389,4 +384,8 @@ and M. Vrac, 2013 : Ensemble reconstruction of the atmospheric column from surface pressure using analogues. Clim. Dyn., 41, 1419-1437. \email{pascal.yiou@lsce.ipsl.fr} } +\author{ +M. Carmen Alvarez-Castro, \email{carmen.alvarez-castro@cmcc.it} +Nuria Perez-Zanon \email{nuria.perez@bsc.es} +} diff --git a/man/BEI_PDFBest.Rd b/man/BEI_PDFBest.Rd index f836ab72..f120258d 100644 --- a/man/BEI_PDFBest.Rd +++ b/man/BEI_PDFBest.Rd @@ -113,12 +113,11 @@ dim(res) # time statistic season # 1 2 2 } -\author{ -Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} -} \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 } - +\author{ +Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} +} diff --git a/man/BEI_Weights.Rd b/man/BEI_Weights.Rd index 61db33af..867a4eb0 100644 --- a/man/BEI_Weights.Rd +++ b/man/BEI_Weights.Rd @@ -43,13 +43,12 @@ dim(res) # sdate dataset member season # 10 3 5 1 -} -\author{ -Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} } \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 } - +\author{ +Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} +} diff --git a/man/CST_Analogs.Rd b/man/CST_Analogs.Rd index 7c9a1e6f..c9166de6 100644 --- a/man/CST_Analogs.Rd +++ b/man/CST_Analogs.Rd @@ -81,11 +81,6 @@ adapted version of the method of Yiou et al 2013. \examples{ res <- CST_Analogs(expL = lonlat_data$exp, obsL = lonlat_data$obs) -} -\author{ -M. Carmen Alvarez-Castro, \email{carmen.alvarez-castro@cmcc.it} - -Nuria Perez-Zanon \email{nuria.perez@bsc.es} } \references{ Yiou, P., T. Salameh, P. Drobinski, L. Menut, R. Vautard, @@ -97,4 +92,8 @@ from surface pressure using analogues. Clim. Dyn., 41, 1419-1437. code{\link{CST_Load}}, \code{\link[s2dverification]{Load}} and \code{\link[s2dverification]{CDORemap}} } +\author{ +M. Carmen Alvarez-Castro, \email{carmen.alvarez-castro@cmcc.it} +Nuria Perez-Zanon \email{nuria.perez@bsc.es} +} diff --git a/man/CST_Anomaly.Rd b/man/CST_Anomaly.Rd index e1c31f0c..b214a31a 100644 --- a/man/CST_Anomaly.Rd +++ b/man/CST_Anomaly.Rd @@ -53,13 +53,12 @@ str(anom3) anom4 <- CST_Anomaly(exp = exp, obs = obs, cross = FALSE, memb = FALSE) str(anom4) +} +\seealso{ +\code{\link[s2dverification]{Ano_CrossValid}}, \code{\link[s2dverification]{Clim}} and \code{\link{CST_Load}} } \author{ Perez-Zanon Nuria, \email{nuria.perez@bsc.es} Pena Jesus, \email{jesus.pena@bsc.es} } -\seealso{ -\code{\link[s2dverification]{Ano_CrossValid}}, \code{\link[s2dverification]{Clim}} and \code{\link{CST_Load}} -} - diff --git a/man/CST_BEI_Weighting.Rd b/man/CST_BEI_Weighting.Rd index 6b9a448a..b2a3f1fa 100644 --- a/man/CST_BEI_Weighting.Rd +++ b/man/CST_BEI_Weighting.Rd @@ -63,12 +63,11 @@ dim(res_CST$data) # time lat lon dataset # 2 3 2 2 } -\author{ -Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} -} \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 } - +\author{ +Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} +} diff --git a/man/CST_BiasCorrection.Rd b/man/CST_BiasCorrection.Rd index 485199ea..a1b415fb 100644 --- a/man/CST_BiasCorrection.Rd +++ b/man/CST_BiasCorrection.Rd @@ -35,10 +35,9 @@ attr(obs, 'class') <- 's2dv_cube' a <- CST_BiasCorrection(exp = exp, obs = obs) str(a) } -\author{ -Verónica Torralba, \email{veronica.torralba@bsc.es} -} \references{ Torralba, V., F.J. Doblas-Reyes, D. MacLeod, I. Christel and M. Davis (2017). Seasonal climate prediction: a new source of information for the management of wind energy resources. Journal of Applied Meteorology and Climatology, 56, 1231-1247, doi:10.1175/JAMC-D-16-0204.1. (CLIM4ENERGY, EUPORIAS, NEWA, RESILIENCE, SPECS) } -\encoding{UTF-8} +\author{ +Verónica Torralba, \email{veronica.torralba@bsc.es} +} diff --git a/man/CST_Calibration.Rd b/man/CST_Calibration.Rd index 36171dbd..48d0a4e1 100644 --- a/man/CST_Calibration.Rd +++ b/man/CST_Calibration.Rd @@ -5,7 +5,7 @@ \title{Forecast Calibration} \usage{ CST_Calibration(exp, obs, cal.method = "mse_min", - eval.method = "leave-one-out", multi.model = F) + eval.method = "leave-one-out", multi.model = F, na.fill = T) } \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}.} @@ -17,6 +17,8 @@ CST_Calibration(exp, obs, cal.method = "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.} \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.} } \value{ an object of class \code{s2dv_cube} containing the calibrated forecasts in the element \code{$data} with the same dimensions of the experimental data. @@ -26,11 +28,6 @@ Four types of member-by-member bias correction can be performed. The \code{bias} Both in-sample or our out-of-sample (leave-one-out cross validation) calibration are possible. } -\author{ -Verónica Torralba, \email{veronica.torralba@bsc.es} - -Bert Van Schaeybroeck, \email{bertvs@meteo.be} -} \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 @@ -57,4 +54,8 @@ attr(obs, 'class') <- 's2dv_cube' a <- CST_Calibration(exp = exp, obs = obs, cal.method = "mse_min", eval.method = "in-sample") str(a) } -\encoding{UTF-8} +\author{ +Verónica Torralba, \email{veronica.torralba@bsc.es} + +Bert Van Schaeybroeck, \email{bertvs@meteo.be} +} diff --git a/man/CST_CategoricalEnsCombination.Rd b/man/CST_CategoricalEnsCombination.Rd index e551c3ec..7175b7fe 100644 --- a/man/CST_CategoricalEnsCombination.Rd +++ b/man/CST_CategoricalEnsCombination.Rd @@ -83,9 +83,6 @@ attr(obs, 'class') <- 's2dv_cube' a <- CST_CategoricalEnsCombination(exp = exp, obs = obs, amt.cat = 3, cat.method = "mmw") } } -\author{ -Bert Van Schaeybroeck, \email{bertvs@meteo.be} -} \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. @@ -93,4 +90,6 @@ Robertson, A. W., Lall, U., Zebiak, S. E., & Goddard, L. (2004). Improved combin 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_EnsClustering.Rd b/man/CST_EnsClustering.Rd index c13bf205..de71d4e3 100644 --- a/man/CST_EnsClustering.Rd +++ b/man/CST_EnsClustering.Rd @@ -125,4 +125,3 @@ Paolo Davini - ISAC-CNR, \email{p.davini@isac.cnr.it} Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} } - diff --git a/man/CST_Load.Rd b/man/CST_Load.Rd index 1fee022c..bf03ba42 100644 --- a/man/CST_Load.Rd +++ b/man/CST_Load.Rd @@ -47,4 +47,3 @@ obs <- CSTools::lonlat_data$obs \author{ Nicolau Manubens, \email{nicolau.manubens@bsc.es} } - diff --git a/man/CST_MultiEOF.Rd b/man/CST_MultiEOF.Rd index fb584751..5fea8a50 100644 --- a/man/CST_MultiEOF.Rd +++ b/man/CST_MultiEOF.Rd @@ -4,8 +4,8 @@ \alias{CST_MultiEOF} \title{EOF analysis of multiple variables} \usage{ -CST_MultiEOF(datalist, neof_max = 40, neof_composed = 5, minvar = 0.6, - lon_lim = NULL, lat_lim = NULL) +CST_MultiEOF(datalist, neof_max = 40, neof_composed = 5, + minvar = 0.6, lon_lim = NULL, lat_lim = NULL) } \arguments{ \item{datalist}{A list of objects of the class 's2dv_cube', containing the variables to be analysed. @@ -69,4 +69,3 @@ Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} Paolo Davini - ISAC-CNR, \email{p.davini@isac.cnr.it} } - diff --git a/man/CST_MultiMetric.Rd b/man/CST_MultiMetric.Rd index 079a5588..8e3ce593 100644 --- a/man/CST_MultiMetric.Rd +++ b/man/CST_MultiMetric.Rd @@ -37,15 +37,14 @@ c(ano_exp, ano_obs) \%<-\% CST_Anomaly(exp = exp, obs = obs, cross = TRUE, memb a <- CST_MultiMetric(exp = ano_exp, obs = ano_obs) str(a) } -\author{ -Mishra Niti, \email{niti.mishra@bsc.es} - -Perez-Zanon Nuria, \email{nuria.perez@bsc.es} -} \references{ Mishra, N., Prodhomme, C., & Guemas, V. (n.d.). Multi-Model Skill Assessment of Seasonal Temperature and Precipitation Forecasts over Europe, 29-31.\url{http://link.springer.com/10.1007/s00382-018-4404-z} } \seealso{ \code{\link[s2dverification]{Corr}}, \code{\link[s2dverification]{RMS}}, \code{\link[s2dverification]{RMSSS}} and \code{\link{CST_Load}} } +\author{ +Mishra Niti, \email{niti.mishra@bsc.es} +Perez-Zanon Nuria, \email{nuria.perez@bsc.es} +} diff --git a/man/CST_MultivarRMSE.Rd b/man/CST_MultivarRMSE.Rd index 685eaf77..24af608c 100644 --- a/man/CST_MultivarRMSE.Rd +++ b/man/CST_MultivarRMSE.Rd @@ -56,10 +56,9 @@ weight <- c(1, 2) a <- CST_MultivarRMSE(exp = ano_exp, obs = ano_obs, weight = weight) str(a) } -\author{ -Deborah Verfaillie, \email{deborah.verfaillie@bsc.es} -} \seealso{ \code{\link[s2dverification]{RMS}} and \code{\link{CST_Load}} } - +\author{ +Deborah Verfaillie, \email{deborah.verfaillie@bsc.es} +} diff --git a/man/CST_QuantileMapping.Rd b/man/CST_QuantileMapping.Rd index 1c93843e..90319622 100644 --- a/man/CST_QuantileMapping.Rd +++ b/man/CST_QuantileMapping.Rd @@ -77,10 +77,9 @@ res <- CST_QuantileMapping(exp = exp, obs = obs, sample_dims = 'time', method = 'DIST') } } -\author{ -Nuria Perez-Zanon, \email{nuria.perez@bsc.es} -} \seealso{ \code{\link[qmap]{fitQmap}} and \code{\link[qmap]{doQmap}} } - +\author{ +Nuria Perez-Zanon, \email{nuria.perez@bsc.es} +} diff --git a/man/CST_RFSlope.Rd b/man/CST_RFSlope.Rd index d2b5aec0..0c4e1671 100644 --- a/man/CST_RFSlope.Rd +++ b/man/CST_RFSlope.Rd @@ -50,4 +50,3 @@ slopes \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 08a7b850..ef5ebe4d 100644 --- a/man/CST_RFWeights.Rd +++ b/man/CST_RFWeights.Rd @@ -47,9 +47,6 @@ nf <- 8 ww <- CST_RFWeights("./worldclim.nc", nf, lon, lat, fsmooth = TRUE) } } -\author{ -Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} -} \references{ Terzago, S., Palazzi, E., & von Hardenberg, J. (2018). Stochastic downscaling of precipitation in complex orography: @@ -57,4 +54,6 @@ 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 . } - +\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 4a667f9a..0ed45f49 100644 --- a/man/CST_RainFARM.Rd +++ b/man/CST_RainFARM.Rd @@ -95,13 +95,12 @@ dim(res$data) # dataset member realization sdate ftime lat lon # 1 2 3 3 4 64 64 -} -\author{ -Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} } \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. } - +\author{ +Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} +} diff --git a/man/CST_SaveExp.Rd b/man/CST_SaveExp.Rd index 17537205..0e49c119 100644 --- a/man/CST_SaveExp.Rd +++ b/man/CST_SaveExp.Rd @@ -29,11 +29,10 @@ destination <- "./path/" CST_SaveExp(data = data, destination = destination) } -} -\author{ -Perez-Zanon Nuria, \email{nuria.perez@bsc.es} } \seealso{ \code{\link{CST_Load}}, \code{\link{as.s2dv_cube}} and \code{\link{s2dv_cube}} } - +\author{ +Perez-Zanon Nuria, \email{nuria.perez@bsc.es} +} diff --git a/man/CST_SplitDim.Rd b/man/CST_SplitDim.Rd index 2019ea7b..8ce20c97 100644 --- a/man/CST_SplitDim.Rd +++ b/man/CST_SplitDim.Rd @@ -4,7 +4,8 @@ \alias{CST_SplitDim} \title{Function to Split Dimension} \usage{ -CST_SplitDim(data, split_dim = "time", indices = NULL, freq = "monthly") +CST_SplitDim(data, split_dim = "time", indices = NULL, + freq = "monthly") } \arguments{ \item{data}{a 's2dv_cube' object} @@ -43,4 +44,3 @@ dim(new_data$data) \author{ Nuria Perez-Zanon, \email{nuria.perez@bsc.es} } - diff --git a/man/EnsClustering.Rd b/man/EnsClustering.Rd index 27aca453..d7284ef5 100644 --- a/man/EnsClustering.Rd +++ b/man/EnsClustering.Rd @@ -67,4 +67,3 @@ Paolo Davini - ISAC-CNR, \email{p.davini@isac.cnr.it} Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} } - diff --git a/man/MultiEOF.Rd b/man/MultiEOF.Rd index 1e822fc4..c38116de 100644 --- a/man/MultiEOF.Rd +++ b/man/MultiEOF.Rd @@ -46,4 +46,3 @@ Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} Paolo Davini - ISAC-CNR, \email{p.davini@isac.cnr.it} } - diff --git a/man/PlotCombinedMap.Rd b/man/PlotCombinedMap.Rd index 6857c64d..62e26904 100644 --- a/man/PlotCombinedMap.Rd +++ b/man/PlotCombinedMap.Rd @@ -5,10 +5,10 @@ \title{Plot Multiple Lon-Lat Variables In a Single Map According to a Decision Function} \usage{ PlotCombinedMap(maps, lon, lat, map_select_fun, display_range, - map_dim = "map", brks = NULL, cols = NULL, col_unknown_map = "white", - mask = NULL, col_mask = "grey", bar_titles = NULL, legend_scale = 1, - fileout = NULL, width = 8, height = 5, size_units = "in", res = 100, - ...) + map_dim = "map", brks = NULL, cols = NULL, + col_unknown_map = "white", mask = NULL, col_mask = "grey", + bar_titles = NULL, legend_scale = 1, fileout = NULL, width = 8, + height = 5, size_units = "in", res = 100, ...) } \arguments{ \item{maps}{List of matrices to plot, each with (longitude, latitude) dimensions, or 3-dimensional array with the dimensions (longitude, latitude, map). Dimension names are required.} @@ -67,12 +67,11 @@ PlotCombinedMap(list(a, b, c), lons, lats, bar_titles = paste('\% of belonging to', c('a', 'b', 'c')), brks = 20, width = 10, height = 8) } +\seealso{ +\code{PlotCombinedMap} and \code{PlotEquiMap} +} \author{ Nicolau Manubens, \email{nicolau.manubens@bsc.es} Veronica Torralba, \email{veronica.torralba@bsc.es} } -\seealso{ -\code{PlotCombinedMap} and \code{PlotEquiMap} -} - diff --git a/man/PlotForecastPDF.Rd b/man/PlotForecastPDF.Rd index bed0bd31..c1959ee8 100644 --- a/man/PlotForecastPDF.Rd +++ b/man/PlotForecastPDF.Rd @@ -4,10 +4,11 @@ \alias{PlotForecastPDF} \title{Plot one or multiple ensemble forecast pdfs for the same event} \usage{ -PlotForecastPDF(fcst, tercile.limits, extreme.limits = NULL, obs = NULL, - plotfile = NULL, title = "Set a title", var.name = "Varname (units)", - fcst.names = NULL, add.ensmemb = c("above", "below", "no"), - color.set = c("ggplot", "s2s4e", "hydro")) +PlotForecastPDF(fcst, tercile.limits, extreme.limits = NULL, + obs = NULL, plotfile = NULL, title = "Set a title", + var.name = "Varname (units)", fcst.names = NULL, + add.ensmemb = c("above", "below", "no"), color.set = c("ggplot", + "s2s4e", "hydro")) } \arguments{ \item{fcst}{a dataframe or array containing all the ensember members for each frecast. If \code{'fcst'} is an array, it should have two labelled dimensions, and one of them should be \code{'members'}. If \code{'fcsts'} is a data.frame, each column shoul be a separate forecast, with the rows beeing the different ensemble members.} @@ -49,4 +50,3 @@ PlotForecastPDF(fcsts2, c(-0.66, 0.66), extreme.limits = c(-1.2, 1.2), \author{ Llorenç Lledó \email{llledo@bsc.es} } -\encoding{UTF-8} diff --git a/man/PlotMostLikelyQuantileMap.Rd b/man/PlotMostLikelyQuantileMap.Rd index 6c92850e..0d984ede 100644 --- a/man/PlotMostLikelyQuantileMap.Rd +++ b/man/PlotMostLikelyQuantileMap.Rd @@ -109,11 +109,10 @@ PlotMostLikelyQuantileMap(bins, lons, lats, mask = 1 - (w1 + w2 / max(c(w1, w2))), brks = 20, width = 10, height = 8) -} -\author{ -Veronica Torralba, \email{veronica.torralba@bsc.es}, Nicolau Manubens, \email{nicolau.manubens@bsc.es} } \seealso{ \code{PlotCombinedMap} and \code{PlotEquiMap} } - +\author{ +Veronica Torralba, \email{veronica.torralba@bsc.es}, Nicolau Manubens, \email{nicolau.manubens@bsc.es} +} diff --git a/man/RFSlope.Rd b/man/RFSlope.Rd index 09a24ff5..5308ef8c 100644 --- a/man/RFSlope.Rd +++ b/man/RFSlope.Rd @@ -60,4 +60,3 @@ slopes \author{ Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} } - diff --git a/man/RainFARM.Rd b/man/RainFARM.Rd index 984dcd42..e0fa9a10 100644 --- a/man/RainFARM.Rd +++ b/man/RainFARM.Rd @@ -4,10 +4,10 @@ \alias{RainFARM} \title{RainFARM stochastic precipitation downscaling (reduced version)} \usage{ -RainFARM(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", drop_realization_dim = FALSE, - verbose = FALSE) +RainFARM(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", + drop_realization_dim = FALSE, verbose = FALSE) } \arguments{ \item{data}{Precipitation array to downscale. @@ -117,4 +117,3 @@ dim(res$data) \author{ Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} } - diff --git a/man/SplitDim.Rd b/man/SplitDim.Rd index e36aa8a5..f07e4756 100644 --- a/man/SplitDim.Rd +++ b/man/SplitDim.Rd @@ -35,4 +35,3 @@ new_data <- SplitDim(data, indices = time, freq = 'year') \author{ Nuria Perez-Zanon, \email{nuria.perez@bsc.es} } - diff --git a/man/areave_data.Rd b/man/areave_data.Rd index cc79c85c..a772220a 100644 --- a/man/areave_data.Rd +++ b/man/areave_data.Rd @@ -41,4 +41,3 @@ areave_data <- Nicolau Manubens \email{nicolau.manubens@bsc.es} } \keyword{data} - diff --git a/man/as.s2dv_cube.Rd b/man/as.s2dv_cube.Rd index 13a2a296..c2b8f3a8 100644 --- a/man/as.s2dv_cube.Rd +++ b/man/as.s2dv_cube.Rd @@ -40,12 +40,11 @@ data <- as.s2dv_cube(data) class(data) } } +\seealso{ +\code{\link{s2dv_cube}}, \code{\link[s2dverification]{Load}}, \code{\link[startR]{Start}} and \code{\link{CST_Load}} +} \author{ Perez-Zanon Nuria, \email{nuria.perez@bsc.es} Nicolau Manubens, \email{nicolau.manubens@bsc.es} } -\seealso{ -\code{\link{s2dv_cube}}, \code{\link[s2dverification]{Load}}, \code{\link[startR]{Start}} and \code{\link{CST_Load}} -} - diff --git a/man/lonlat_data.Rd b/man/lonlat_data.Rd index eca7abac..0c6ee30f 100644 --- a/man/lonlat_data.Rd +++ b/man/lonlat_data.Rd @@ -41,4 +41,3 @@ lonlat_data <- Nicolau Manubens \email{nicolau.manubens@bsc.es} } \keyword{data} - diff --git a/man/lonlat_prec.Rd b/man/lonlat_prec.Rd index 69cb94e8..345e3cab 100644 --- a/man/lonlat_prec.Rd +++ b/man/lonlat_prec.Rd @@ -29,4 +29,3 @@ lonlat_prec <- CST_Load('prlr', exp = list(infile), obs = NULL, Jost von Hardenberg \email{j.vonhardenberg@isac.cnr.it} } \keyword{data} - diff --git a/man/s2dv_cube.Rd b/man/s2dv_cube.Rd index 48af7bbb..f57d5ed3 100644 --- a/man/s2dv_cube.Rd +++ b/man/s2dv_cube.Rd @@ -75,10 +75,9 @@ exp8 <- s2dv_cube(data = exp_original, lon = seq(-10, 10, 5), lat = c(45, 50), end = paste0(rep("31", 10), rep("01", 10), 1990:1999))) class(exp8) } -\author{ -Perez-Zanon Nuria, \email{nuria.perez@bsc.es} -} \seealso{ \code{\link[s2dverification]{Load}} and \code{\link{CST_Load}} } - +\author{ +Perez-Zanon Nuria, \email{nuria.perez@bsc.es} +} -- GitLab From 08b1c532b7af46ce62fbfff656aab638ba18c8c1 Mon Sep 17 00:00:00 2001 From: Bert Van schaeybroeck Date: Fri, 24 Jan 2020 12:28:34 +0100 Subject: [PATCH 2/4] 1) Introduction of ncores as extra parameter. 2) Introduction of Calibration as a new function (replacement of .calibration.wrap). 3) removal of var.fc --- R/CST_Calibration.R | 108 ++++++++++++++++++++++++++++------------- man/CST_Calibration.Rd | 29 +++++------ man/Calibration.Rd | 48 ++++++++++++++++++ 3 files changed, 132 insertions(+), 53 deletions(-) create mode 100644 man/Calibration.Rd diff --git a/R/CST_Calibration.R b/R/CST_Calibration.R index efc7eeaa..59aff385 100644 --- a/R/CST_Calibration.R +++ b/R/CST_Calibration.R @@ -2,11 +2,7 @@ #' #'@author Verónica Torralba, \email{veronica.torralba@bsc.es} #'@author Bert Van Schaeybroeck, \email{bertvs@meteo.be} -#'@description Four 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). -#'@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 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 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 forecast experiment data in the element named \code{$data}. #'@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}. @@ -14,16 +10,16 @@ #'@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 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. -#'@return an object of class \code{s2dv_cube} containing the calibrated forecasts in the element \code{$data} with the same dimensions of the experimental data. +#'@param ncores is an integer that indicates the number of cores for parallel computations using multiApply function. +#'@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. #' #'@import s2dverification #'@import abind #' #'@seealso \code{\link{CST_Load}} #' -#'# Example -#'# Creation of sample s2dverification objects. These are not complete -#'# s2dverification objects though. The Load function returns complete objects. +#'@examples +#'# Example 1: #'mod1 <- 1 : (1 * 3 * 4 * 5 * 6 * 7) #'dim(mod1) <- c(dataset = 1, member = 3, sdate = 4, ftime = 5, lat = 6, lon = 7) #'obs1 <- 1 : (1 * 1 * 4 * 5 * 6 * 7) @@ -38,8 +34,12 @@ #'str(a) #'@export -CST_Calibration <- function(exp, obs, cal.method = "mse_min", - eval.method = "leave-one-out", multi.model = F, na.fill = T) { +CST_Calibration <- function(exp, obs, + cal.method = "mse_min", + eval.method = "leave-one-out", + multi.model = F, + na.fill = T, + ncores = NULL) { if (!inherits(exp, "s2dv_cube") || !inherits(obs, "s2dv_cube")) { stop("Parameter 'exp' and 'obs' must be of the class 's2dv_cube', ", "as output by CSTools::CST_Load.") @@ -53,9 +53,12 @@ CST_Calibration <- function(exp, obs, cal.method = "mse_min", if(!missing(multi.model) & !(cal.method == "mse_min")){ warning(paste0("The multi.model parameter is ignored when using the calibration method ", cal.method)) } - exp$data <- .calibration.wrap(exp = exp$data, obs = obs$data, - cal.method = cal.method, eval.method = eval.method, - multi.model = multi.model, na.fill = na.fill) + exp$data <- Calibration(exp = exp$data, obs = obs$data, + cal.method = cal.method, + eval.method = eval.method, + multi.model = multi.model, + na.fill = na.fill, + ncores = ncores) exp$Datasets <- c(exp$Datasets, obs$Datasets) exp$source_files <- c(exp$source_files, obs$source_files) @@ -63,15 +66,39 @@ CST_Calibration <- function(exp, obs, cal.method = "mse_min", } -.data.set.sufficiently.large <- function(mod, obs){ - amt.min.samples <- 3 - amt.good.pts <- sum(!is.na(obs) & !apply(mod, c(2), function(x) all(is.na(x)))) - return(amt.good.pts > amt.min.samples) -} -.calibration.wrap <- function(exp, obs, cal.method, - eval.method, multi.model, na.fill) { +#'Forecast Calibration +#' +#'@author Verónica Torralba, \email{veronica.torralba@bsc.es} +#'@author Bert Van Schaeybroeck, \email{bertvs@meteo.be} +#'@description Four 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). +#'@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 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 an array containing the seasonal forecast experiment data. +#'@param obs an array containing the observed data. +#'@param cal.method is the calibration method used, can be either \code{bias}, \code{evmos}, \code{mse_min} or \code{crps_min}. 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. +#'@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 ncores is an integer that indicates the number of cores for parallel computations using multiApply function. +#'@return an array containing the calibrated forecasts with the same dimensions as the \code{exp} array. +#' +#'@import s2dverification +#'@import abind +#' +#'@seealso \code{\link{CST_Load}} +#' + +Calibration <- function(exp, obs, + cal.method = "mse_min", + eval.method = "leave-one-out", + multi.model = F, + na.fill = T, + ncores = NULL) { dim.exp <- dim(exp) amt.dims.exp <- length(dim.exp) @@ -103,10 +130,14 @@ CST_Calibration <- function(exp, obs, cal.method = "mse_min", stop("Parameter 'obs' must have a member dimension with length=1") } + ncores.to.use <- ifelse(is.null(ncores), 1, ncores) + obs <- Subset(obs, along = "member", indices = 1, drop = "selected") - data.set.sufficiently.large.out <- Apply(data = list(mod = exp, obs = obs), - target_dims = list(mod = target.dim.names.exp, obs = target.dim.names.obs), + data.set.sufficiently.large.out <- + Apply(data = list(exp = exp, obs = obs), + target_dims = list(exp = target.dim.names.exp, obs = target.dim.names.obs), + ncores = ncores.to.use, fun = .data.set.sufficiently.large)$output1 if(!all(data.set.sufficiently.large.out)){ @@ -117,12 +148,13 @@ CST_Calibration <- function(exp, obs, cal.method = "mse_min", } } - calibrated <- Apply(data = list(mod = exp, obs = obs), + calibrated <- Apply(data = list(exp = exp, obs = obs), cal.method = cal.method, eval.method = eval.method, multi.model = multi.model, na.fill = na.fill, - target_dims = list(mod = target.dim.names.exp, obs = target.dim.names.obs), + target_dims = list(exp = target.dim.names.exp, obs = target.dim.names.obs), + ncores = ncores.to.use, fun = .cal)$output1 dexes <- match(names(dim(exp)), names(dim(calibrated))) @@ -133,6 +165,13 @@ CST_Calibration <- function(exp, obs, cal.method = "mse_min", return(calibrated) } + +.data.set.sufficiently.large <- function(exp, obs){ + amt.min.samples <- 3 + amt.good.pts <- sum(!is.na(obs) & !apply(exp, c(2), function(x) all(is.na(x)))) + return(amt.good.pts > amt.min.samples) +} + .make.eval.train.dexes <- function(eval.method, amt.points){ if(eval.method == "leave-one-out"){ dexes.lst <- lapply(seq(1, amt.points), function(x) return(list(eval.dexes = x, train.dexes = seq(1, amt.points)[-x]))) @@ -144,21 +183,20 @@ CST_Calibration <- function(exp, obs, cal.method = "mse_min", return(dexes.lst) } -.cal <- function(mod, obs, cal.method, eval.method, multi.model, na.fill) { +.cal <- function(exp, obs, cal.method, eval.method, multi.model, na.fill) { - var.obs <- as.vector(obs) - var.fc <- mod - dims.fc <- dim(var.fc) + obs <- as.vector(obs) + dims.fc <- dim(exp) amt.mbr <- dims.fc[1] amt.sdate <- dims.fc[2] - var.cor.fc <- NA * var.fc + var.cor.fc <- NA * exp names(dim(var.cor.fc)) <- c("member", "sdate") - if(!.data.set.sufficiently.large(mod = mod, obs = obs)){ + if(!.data.set.sufficiently.large(exp = exp, obs = obs)){ if(na.fill){ return(var.cor.fc) } else { - var.cor.fc[] <- var.fc[] + var.cor.fc[] <- exp[] return(var.cor.fc) } } @@ -170,9 +208,9 @@ CST_Calibration <- function(exp, obs, cal.method = "mse_min", eval.dexes <- eval.train.dexeses[[i.sample]]$eval.dexes train.dexes <- eval.train.dexeses[[i.sample]]$train.dexes - fc.ev <- var.fc[ , eval.dexes, drop = FALSE] - fc.tr <- var.fc[ , train.dexes] - obs.tr <- var.obs[train.dexes , drop = FALSE] + fc.ev <- exp[ , eval.dexes, drop = FALSE] + fc.tr <- exp[ , train.dexes] + obs.tr <- obs[train.dexes , drop = FALSE] if(cal.method == "bias"){ var.cor.fc[ , eval.dexes] <- fc.ev + mean(obs.tr, na.rm = TRUE) - mean(fc.tr, na.rm = TRUE) diff --git a/man/CST_Calibration.Rd b/man/CST_Calibration.Rd index 48d0a4e1..9fa594b6 100644 --- a/man/CST_Calibration.Rd +++ b/man/CST_Calibration.Rd @@ -5,7 +5,8 @@ \title{Forecast Calibration} \usage{ CST_Calibration(exp, obs, cal.method = "mse_min", - eval.method = "leave-one-out", multi.model = F, na.fill = T) + eval.method = "leave-one-out", multi.model = F, na.fill = T, + ncores = NULL) } \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}.} @@ -19,28 +20,17 @@ CST_Calibration(exp, obs, cal.method = "mse_min", \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{ncores}{is an integer that indicates the number of cores for parallel computations using multiApply function.} } \value{ -an object of class \code{s2dv_cube} containing the calibrated forecasts in the element \code{$data} with the same dimensions of the experimental data. +an object of class \code{s2dv_cube} containing the calibrated forecasts in the element \code{$data} with the same dimensions of the exp data. } \description{ -Four 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). - -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 - -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 +Equivalent to function \code{Calibration} but for objects of class \code{s2dv_cube}. } -\seealso{ -\code{\link{CST_Load}} - -# Example -# Creation of sample s2dverification objects. These are not complete -# s2dverification objects though. The Load function returns complete objects. +\examples{ +# Example 1: mod1 <- 1 : (1 * 3 * 4 * 5 * 6 * 7) dim(mod1) <- c(dataset = 1, member = 3, sdate = 4, ftime = 5, lat = 6, lon = 7) obs1 <- 1 : (1 * 1 * 4 * 5 * 6 * 7) @@ -54,6 +44,9 @@ attr(obs, 'class') <- 's2dv_cube' a <- CST_Calibration(exp = exp, obs = obs, cal.method = "mse_min", eval.method = "in-sample") str(a) } +\seealso{ +\code{\link{CST_Load}} +} \author{ Verónica Torralba, \email{veronica.torralba@bsc.es} diff --git a/man/Calibration.Rd b/man/Calibration.Rd new file mode 100644 index 00000000..2f7ddeac --- /dev/null +++ b/man/Calibration.Rd @@ -0,0 +1,48 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/CST_Calibration.R +\name{Calibration} +\alias{Calibration} +\title{Forecast Calibration} +\usage{ +Calibration(exp, obs, cal.method = "mse_min", + eval.method = "leave-one-out", multi.model = F, na.fill = T, + ncores = NULL) +} +\arguments{ +\item{exp}{an array containing the seasonal forecast experiment data in the element named \code{$data}.} + +\item{obs}{an array containing the observed data in the element named \code{$data}.} + +\item{cal.method}{is the calibration method used, can be either \code{bias}, \code{evmos}, \code{mse_min} or \code{crps_min}. 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.} + +\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{ncores}{is an integer that indicates the number of cores for parallel computations using multiApply function.} +} +\value{ +an array containing the calibrated forecasts with the same dimensions of the exp data. +} +\description{ +Four 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). + +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 + +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}} +} +\author{ +Verónica Torralba, \email{veronica.torralba@bsc.es} + +Bert Van Schaeybroeck, \email{bertvs@meteo.be} +} -- GitLab From d3996e4535b9e3a83e91bce0cf52cad23ecaab17 Mon Sep 17 00:00:00 2001 From: Bert Van schaeybroeck Date: Fri, 24 Jan 2020 12:51:29 +0100 Subject: [PATCH 3/4] Additional change: 4)introduce BFGS method for the crps_min method --- NAMESPACE | 1 + R/CST_Calibration.R | 40 +++++++++++++++++++++++++++++----------- 2 files changed, 30 insertions(+), 11 deletions(-) diff --git a/NAMESPACE b/NAMESPACE index e7d7c003..ce1737bc 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -8,6 +8,7 @@ export(CST_Anomaly) export(CST_BEI_Weighting) export(CST_BiasCorrection) export(CST_Calibration) +export(Calibration) export(CST_CategoricalEnsCombination) export(CST_EnsClustering) export(CST_Load) diff --git a/R/CST_Calibration.R b/R/CST_Calibration.R index 59aff385..a7f1924b 100644 --- a/R/CST_Calibration.R +++ b/R/CST_Calibration.R @@ -10,7 +10,7 @@ #'@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 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 ncores is an integer that indicates the number of cores for parallel computations using multiApply function. +#'@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. #' #'@import s2dverification @@ -39,7 +39,7 @@ CST_Calibration <- function(exp, obs, eval.method = "leave-one-out", multi.model = F, na.fill = T, - ncores = NULL) { + ncores = 1) { if (!inherits(exp, "s2dv_cube") || !inherits(obs, "s2dv_cube")) { stop("Parameter 'exp' and 'obs' must be of the class 's2dv_cube', ", "as output by CSTools::CST_Load.") @@ -84,7 +84,7 @@ CST_Calibration <- function(exp, obs, #'@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 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 ncores is an integer that indicates the number of cores for parallel computations using multiApply function. +#'@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. #' #'@import s2dverification @@ -98,7 +98,7 @@ Calibration <- function(exp, obs, eval.method = "leave-one-out", multi.model = F, na.fill = T, - ncores = NULL) { + ncores = 1) { dim.exp <- dim(exp) amt.dims.exp <- length(dim.exp) @@ -129,15 +129,13 @@ Calibration <- function(exp, obs, if (dim(obs)['member']!=1){ stop("Parameter 'obs' must have a member dimension with length=1") } - - ncores.to.use <- ifelse(is.null(ncores), 1, ncores) - + obs <- Subset(obs, along = "member", indices = 1, drop = "selected") data.set.sufficiently.large.out <- Apply(data = list(exp = exp, obs = obs), target_dims = list(exp = target.dim.names.exp, obs = target.dim.names.obs), - ncores = ncores.to.use, + ncores = ncores, fun = .data.set.sufficiently.large)$output1 if(!all(data.set.sufficiently.large.out)){ @@ -154,7 +152,7 @@ Calibration <- function(exp, obs, multi.model = multi.model, na.fill = na.fill, target_dims = list(exp = target.dim.names.exp, obs = target.dim.names.obs), - ncores = ncores.to.use, + ncores = ncores, fun = .cal)$output1 dexes <- match(names(dim(exp)), names(dim(calibrated))) @@ -235,8 +233,11 @@ Calibration <- function(exp, obs, init.par <- c(.calc.mse.min.par(quant.obs.fc.tr), 0.001) init.par[3] <- sqrt(init.par[3]) #calculate regression parameters on training dataset - optim.tmp <- optim(par = init.par, fn = .calc.crps.opt, - quant.obs.fc = quant.obs.fc.tr, method = "Nelder-Mead") + optim.tmp <- optim(par = init.par, + fn = .calc.crps.opt, + gr = .calc.crps.grad.opt, + quant.obs.fc = quant.obs.fc.tr, + method = "BFGS") mbm.par <- optim.tmp$par #correct evaluation subset @@ -363,6 +364,23 @@ Calibration <- function(exp, obs, ) } +.calc.crps.grad.opt <- function(par, quant.obs.fc){ + sgn1 <- with(quant.obs.fc,sign(obs.per.ens - + (par[1] + par[2] * fc.ens.av.per.ens + + ((par[3])^2 + par[4] / spr.abs.per.ens) * fc.dev))) + sgn2 <- with(quant.obs.fc, sign((par[3])^2 + par[4] / spr.abs.per.ens)) + sgn3 <- with(quant.obs.fc,sign((par[3])^2 * spr.abs + par[4])) + deriv.par1 <- mean(sgn1, na.rm = TRUE) + deriv.par2 <- with(quant.obs.fc, mean(sgn1 * fc.dev, na.rm = TRUE)) + deriv.par3 <- with(quant.obs.fc, + mean(2* par[3] * sgn1 * sgn2 * fc.ens.av.per.ens, na.rm = TRUE) - + mean(spr.abs * sgn3, na.rm = TRUE) / 2.) + deriv.par4 <- with(quant.obs.fc, + mean(sgn1 * sgn2 * fc.ens.av.per.ens / spr.abs.per.ens, na.rm = TRUE) - + mean(sgn3, na.rm = TRUE) / 2.) + return(c(deriv.par1, deriv.par2, deriv.par3, deriv.par4)) +} + #Below are the core or elementary functions to correct the evaluation set based on the regression parameters .correct.evmos.fc <- function(fc, par){ quant.fc.mp <- .calc.fc.quant(fc = fc) -- GitLab From 1c403ccfb3f3c9bf4abefde19da8329d4911b227 Mon Sep 17 00:00:00 2001 From: nperez Date: Fri, 7 Feb 2020 18:46:32 +0100 Subject: [PATCH 4/4] automatic documentation generated with devtools --- DESCRIPTION | 2 +- NAMESPACE | 1 - man/Analogs.Rd | 13 +++++++------ man/BEI_PDFBest.Rd | 7 ++++--- man/BEI_Weights.Rd | 7 ++++--- man/CST_Analogs.Rd | 9 +++++---- man/CST_Anomaly.Rd | 7 ++++--- man/CST_BEI_Weighting.Rd | 7 ++++--- man/CST_BiasCorrection.Rd | 7 ++++--- man/CST_Calibration.Rd | 13 +++++++------ man/CST_CategoricalEnsCombination.Rd | 7 ++++--- man/CST_EnsClustering.Rd | 1 + man/CST_Load.Rd | 1 + man/CST_MultiEOF.Rd | 5 +++-- man/CST_MultiMetric.Rd | 9 +++++---- man/CST_MultivarRMSE.Rd | 7 ++++--- man/CST_QuantileMapping.Rd | 7 ++++--- man/CST_RFSlope.Rd | 1 + man/CST_RFWeights.Rd | 7 ++++--- man/CST_RainFARM.Rd | 7 ++++--- man/CST_SaveExp.Rd | 7 ++++--- man/CST_SplitDim.Rd | 4 ++-- man/Calibration.Rd | 22 +++++++++++----------- man/EnsClustering.Rd | 1 + man/MultiEOF.Rd | 1 + man/PlotCombinedMap.Rd | 15 ++++++++------- man/PlotForecastPDF.Rd | 10 +++++----- man/PlotMostLikelyQuantileMap.Rd | 7 ++++--- man/RFSlope.Rd | 1 + man/RainFARM.Rd | 9 +++++---- man/SplitDim.Rd | 1 + man/areave_data.Rd | 1 + man/as.s2dv_cube.Rd | 7 ++++--- man/lonlat_data.Rd | 1 + man/lonlat_prec.Rd | 1 + man/s2dv_cube.Rd | 7 ++++--- 36 files changed, 125 insertions(+), 95 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index c3de9d84..0e47736a 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -70,4 +70,4 @@ VignetteBuilder: knitr License: Apache License 2.0 Encoding: UTF-8 LazyData: true -RoxygenNote: 6.1.1 +RoxygenNote: 5.0.0 diff --git a/NAMESPACE b/NAMESPACE index 9c766759..bd5d0f16 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -8,7 +8,6 @@ export(CST_Anomaly) export(CST_BEI_Weighting) export(CST_BiasCorrection) export(CST_Calibration) -export(Calibration) export(CST_CategoricalEnsCombination) export(CST_EnsClustering) export(CST_Load) diff --git a/man/Analogs.Rd b/man/Analogs.Rd index 52d9ff97..ee8a737e 100644 --- a/man/Analogs.Rd +++ b/man/Analogs.Rd @@ -5,8 +5,8 @@ \title{Analogs based on large scale fields.} \usage{ Analogs(expL, obsL, time_obsL, expVar = NULL, obsVar = NULL, - criteria = "Large_dist", lonVar = NULL, latVar = NULL, - region = NULL, nAnalogs = NULL, return_list = FALSE) + criteria = "Large_dist", lonVar = NULL, latVar = NULL, region = NULL, + nAnalogs = NULL, return_list = FALSE) } \arguments{ \item{expL}{an array of N named dimensions containing the experimental field @@ -377,6 +377,11 @@ Local_scalecor <- Analogs(expL=expSLP, str(Local_scalecor) Local_scalecor$AnalogsInfo +} +\author{ +M. Carmen Alvarez-Castro, \email{carmen.alvarez-castro@cmcc.it} + +Nuria Perez-Zanon \email{nuria.perez@bsc.es} } \references{ Yiou, P., T. Salameh, P. Drobinski, L. Menut, R. Vautard, @@ -384,8 +389,4 @@ and M. Vrac, 2013 : Ensemble reconstruction of the atmospheric column from surface pressure using analogues. Clim. Dyn., 41, 1419-1437. \email{pascal.yiou@lsce.ipsl.fr} } -\author{ -M. Carmen Alvarez-Castro, \email{carmen.alvarez-castro@cmcc.it} -Nuria Perez-Zanon \email{nuria.perez@bsc.es} -} diff --git a/man/BEI_PDFBest.Rd b/man/BEI_PDFBest.Rd index f120258d..f836ab72 100644 --- a/man/BEI_PDFBest.Rd +++ b/man/BEI_PDFBest.Rd @@ -113,11 +113,12 @@ dim(res) # time statistic season # 1 2 2 } +\author{ +Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} +} \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 } -\author{ -Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} -} + diff --git a/man/BEI_Weights.Rd b/man/BEI_Weights.Rd index 867a4eb0..61db33af 100644 --- a/man/BEI_Weights.Rd +++ b/man/BEI_Weights.Rd @@ -43,12 +43,13 @@ dim(res) # sdate dataset member season # 10 3 5 1 +} +\author{ +Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} } \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 } -\author{ -Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} -} + diff --git a/man/CST_Analogs.Rd b/man/CST_Analogs.Rd index c9166de6..7c9a1e6f 100644 --- a/man/CST_Analogs.Rd +++ b/man/CST_Analogs.Rd @@ -81,6 +81,11 @@ adapted version of the method of Yiou et al 2013. \examples{ res <- CST_Analogs(expL = lonlat_data$exp, obsL = lonlat_data$obs) +} +\author{ +M. Carmen Alvarez-Castro, \email{carmen.alvarez-castro@cmcc.it} + +Nuria Perez-Zanon \email{nuria.perez@bsc.es} } \references{ Yiou, P., T. Salameh, P. Drobinski, L. Menut, R. Vautard, @@ -92,8 +97,4 @@ from surface pressure using analogues. Clim. Dyn., 41, 1419-1437. code{\link{CST_Load}}, \code{\link[s2dverification]{Load}} and \code{\link[s2dverification]{CDORemap}} } -\author{ -M. Carmen Alvarez-Castro, \email{carmen.alvarez-castro@cmcc.it} -Nuria Perez-Zanon \email{nuria.perez@bsc.es} -} diff --git a/man/CST_Anomaly.Rd b/man/CST_Anomaly.Rd index b214a31a..e1c31f0c 100644 --- a/man/CST_Anomaly.Rd +++ b/man/CST_Anomaly.Rd @@ -53,12 +53,13 @@ str(anom3) anom4 <- CST_Anomaly(exp = exp, obs = obs, cross = FALSE, memb = FALSE) str(anom4) -} -\seealso{ -\code{\link[s2dverification]{Ano_CrossValid}}, \code{\link[s2dverification]{Clim}} and \code{\link{CST_Load}} } \author{ Perez-Zanon Nuria, \email{nuria.perez@bsc.es} Pena Jesus, \email{jesus.pena@bsc.es} } +\seealso{ +\code{\link[s2dverification]{Ano_CrossValid}}, \code{\link[s2dverification]{Clim}} and \code{\link{CST_Load}} +} + diff --git a/man/CST_BEI_Weighting.Rd b/man/CST_BEI_Weighting.Rd index 8cb4522a..0e60a356 100644 --- a/man/CST_BEI_Weighting.Rd +++ b/man/CST_BEI_Weighting.Rd @@ -68,11 +68,12 @@ dim(res_CST$data) # time lat lon dataset # 2 3 2 2 } +\author{ +Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} +} \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 } -\author{ -Eroteida Sanchez-Garcia - AEMET, \email{esanchezg@aemet.es} -} + diff --git a/man/CST_BiasCorrection.Rd b/man/CST_BiasCorrection.Rd index a1b415fb..e8a82af0 100644 --- a/man/CST_BiasCorrection.Rd +++ b/man/CST_BiasCorrection.Rd @@ -35,9 +35,10 @@ attr(obs, 'class') <- 's2dv_cube' a <- CST_BiasCorrection(exp = exp, obs = obs) str(a) } -\references{ -Torralba, V., F.J. Doblas-Reyes, D. MacLeod, I. Christel and M. Davis (2017). Seasonal climate prediction: a new source of information for the management of wind energy resources. Journal of Applied Meteorology and Climatology, 56, 1231-1247, doi:10.1175/JAMC-D-16-0204.1. (CLIM4ENERGY, EUPORIAS, NEWA, RESILIENCE, SPECS) -} \author{ Verónica Torralba, \email{veronica.torralba@bsc.es} } +\references{ +Torralba, V., F.J. Doblas-Reyes, D. MacLeod, I. Christel and M. Davis (2017). Seasonal climate prediction: a new source of information for the management of wind energy resources. Journal of Applied Meteorology and Climatology, 56, 1231-1247, doi:10.1175/JAMC-D-16-0204.1. (CLIM4ENERGY, EUPORIAS, NEWA, RESILIENCE, SPECS) +} + diff --git a/man/CST_Calibration.Rd b/man/CST_Calibration.Rd index 9fa594b6..ed880aab 100644 --- a/man/CST_Calibration.Rd +++ b/man/CST_Calibration.Rd @@ -6,7 +6,7 @@ \usage{ CST_Calibration(exp, obs, cal.method = "mse_min", eval.method = "leave-one-out", multi.model = F, na.fill = T, - ncores = NULL) + ncores = 1) } \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}.} @@ -21,10 +21,10 @@ CST_Calibration(exp, obs, cal.method = "mse_min", \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{ncores}{is an integer that indicates the number of cores for parallel computations using multiApply function.} +\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 of the exp data. +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}. @@ -44,11 +44,12 @@ attr(obs, 'class') <- 's2dv_cube' a <- CST_Calibration(exp = exp, obs = obs, cal.method = "mse_min", eval.method = "in-sample") str(a) } -\seealso{ -\code{\link{CST_Load}} -} \author{ Verónica Torralba, \email{veronica.torralba@bsc.es} Bert Van Schaeybroeck, \email{bertvs@meteo.be} } +\seealso{ +\code{\link{CST_Load}} +} + diff --git a/man/CST_CategoricalEnsCombination.Rd b/man/CST_CategoricalEnsCombination.Rd index 7175b7fe..e551c3ec 100644 --- a/man/CST_CategoricalEnsCombination.Rd +++ b/man/CST_CategoricalEnsCombination.Rd @@ -83,6 +83,9 @@ attr(obs, 'class') <- 's2dv_cube' a <- CST_CategoricalEnsCombination(exp = exp, obs = obs, amt.cat = 3, cat.method = "mmw") } } +\author{ +Bert Van Schaeybroeck, \email{bertvs@meteo.be} +} \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. @@ -90,6 +93,4 @@ Robertson, A. W., Lall, U., Zebiak, S. E., & Goddard, L. (2004). Improved combin 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_EnsClustering.Rd b/man/CST_EnsClustering.Rd index de71d4e3..c13bf205 100644 --- a/man/CST_EnsClustering.Rd +++ b/man/CST_EnsClustering.Rd @@ -125,3 +125,4 @@ Paolo Davini - ISAC-CNR, \email{p.davini@isac.cnr.it} Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} } + diff --git a/man/CST_Load.Rd b/man/CST_Load.Rd index bf03ba42..1fee022c 100644 --- a/man/CST_Load.Rd +++ b/man/CST_Load.Rd @@ -47,3 +47,4 @@ obs <- CSTools::lonlat_data$obs \author{ Nicolau Manubens, \email{nicolau.manubens@bsc.es} } + diff --git a/man/CST_MultiEOF.Rd b/man/CST_MultiEOF.Rd index 5fea8a50..fb584751 100644 --- a/man/CST_MultiEOF.Rd +++ b/man/CST_MultiEOF.Rd @@ -4,8 +4,8 @@ \alias{CST_MultiEOF} \title{EOF analysis of multiple variables} \usage{ -CST_MultiEOF(datalist, neof_max = 40, neof_composed = 5, - minvar = 0.6, lon_lim = NULL, lat_lim = NULL) +CST_MultiEOF(datalist, neof_max = 40, neof_composed = 5, minvar = 0.6, + lon_lim = NULL, lat_lim = NULL) } \arguments{ \item{datalist}{A list of objects of the class 's2dv_cube', containing the variables to be analysed. @@ -69,3 +69,4 @@ Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} Paolo Davini - ISAC-CNR, \email{p.davini@isac.cnr.it} } + diff --git a/man/CST_MultiMetric.Rd b/man/CST_MultiMetric.Rd index 8e3ce593..079a5588 100644 --- a/man/CST_MultiMetric.Rd +++ b/man/CST_MultiMetric.Rd @@ -37,14 +37,15 @@ c(ano_exp, ano_obs) \%<-\% CST_Anomaly(exp = exp, obs = obs, cross = TRUE, memb a <- CST_MultiMetric(exp = ano_exp, obs = ano_obs) str(a) } +\author{ +Mishra Niti, \email{niti.mishra@bsc.es} + +Perez-Zanon Nuria, \email{nuria.perez@bsc.es} +} \references{ Mishra, N., Prodhomme, C., & Guemas, V. (n.d.). Multi-Model Skill Assessment of Seasonal Temperature and Precipitation Forecasts over Europe, 29-31.\url{http://link.springer.com/10.1007/s00382-018-4404-z} } \seealso{ \code{\link[s2dverification]{Corr}}, \code{\link[s2dverification]{RMS}}, \code{\link[s2dverification]{RMSSS}} and \code{\link{CST_Load}} } -\author{ -Mishra Niti, \email{niti.mishra@bsc.es} -Perez-Zanon Nuria, \email{nuria.perez@bsc.es} -} diff --git a/man/CST_MultivarRMSE.Rd b/man/CST_MultivarRMSE.Rd index 24af608c..685eaf77 100644 --- a/man/CST_MultivarRMSE.Rd +++ b/man/CST_MultivarRMSE.Rd @@ -56,9 +56,10 @@ weight <- c(1, 2) a <- CST_MultivarRMSE(exp = ano_exp, obs = ano_obs, weight = weight) str(a) } -\seealso{ -\code{\link[s2dverification]{RMS}} and \code{\link{CST_Load}} -} \author{ Deborah Verfaillie, \email{deborah.verfaillie@bsc.es} } +\seealso{ +\code{\link[s2dverification]{RMS}} and \code{\link{CST_Load}} +} + diff --git a/man/CST_QuantileMapping.Rd b/man/CST_QuantileMapping.Rd index 90319622..1c93843e 100644 --- a/man/CST_QuantileMapping.Rd +++ b/man/CST_QuantileMapping.Rd @@ -77,9 +77,10 @@ res <- CST_QuantileMapping(exp = exp, obs = obs, sample_dims = 'time', method = 'DIST') } } -\seealso{ -\code{\link[qmap]{fitQmap}} and \code{\link[qmap]{doQmap}} -} \author{ Nuria Perez-Zanon, \email{nuria.perez@bsc.es} } +\seealso{ +\code{\link[qmap]{fitQmap}} and \code{\link[qmap]{doQmap}} +} + diff --git a/man/CST_RFSlope.Rd b/man/CST_RFSlope.Rd index 0c4e1671..d2b5aec0 100644 --- a/man/CST_RFSlope.Rd +++ b/man/CST_RFSlope.Rd @@ -50,3 +50,4 @@ slopes \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 ef5ebe4d..08a7b850 100644 --- a/man/CST_RFWeights.Rd +++ b/man/CST_RFWeights.Rd @@ -47,6 +47,9 @@ nf <- 8 ww <- CST_RFWeights("./worldclim.nc", nf, lon, lat, fsmooth = TRUE) } } +\author{ +Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} +} \references{ Terzago, S., Palazzi, E., & von Hardenberg, J. (2018). Stochastic downscaling of precipitation in complex orography: @@ -54,6 +57,4 @@ 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 . } -\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 0ed45f49..4a667f9a 100644 --- a/man/CST_RainFARM.Rd +++ b/man/CST_RainFARM.Rd @@ -95,12 +95,13 @@ dim(res$data) # dataset member realization sdate ftime lat lon # 1 2 3 3 4 64 64 +} +\author{ +Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} } \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. } -\author{ -Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} -} + diff --git a/man/CST_SaveExp.Rd b/man/CST_SaveExp.Rd index 0e49c119..17537205 100644 --- a/man/CST_SaveExp.Rd +++ b/man/CST_SaveExp.Rd @@ -29,10 +29,11 @@ destination <- "./path/" CST_SaveExp(data = data, destination = destination) } -} -\seealso{ -\code{\link{CST_Load}}, \code{\link{as.s2dv_cube}} and \code{\link{s2dv_cube}} } \author{ Perez-Zanon Nuria, \email{nuria.perez@bsc.es} } +\seealso{ +\code{\link{CST_Load}}, \code{\link{as.s2dv_cube}} and \code{\link{s2dv_cube}} +} + diff --git a/man/CST_SplitDim.Rd b/man/CST_SplitDim.Rd index 8ce20c97..2019ea7b 100644 --- a/man/CST_SplitDim.Rd +++ b/man/CST_SplitDim.Rd @@ -4,8 +4,7 @@ \alias{CST_SplitDim} \title{Function to Split Dimension} \usage{ -CST_SplitDim(data, split_dim = "time", indices = NULL, - freq = "monthly") +CST_SplitDim(data, split_dim = "time", indices = NULL, freq = "monthly") } \arguments{ \item{data}{a 's2dv_cube' object} @@ -44,3 +43,4 @@ dim(new_data$data) \author{ Nuria Perez-Zanon, \email{nuria.perez@bsc.es} } + diff --git a/man/Calibration.Rd b/man/Calibration.Rd index 2f7ddeac..4290abd7 100644 --- a/man/Calibration.Rd +++ b/man/Calibration.Rd @@ -4,14 +4,13 @@ \alias{Calibration} \title{Forecast Calibration} \usage{ -Calibration(exp, obs, cal.method = "mse_min", - eval.method = "leave-one-out", multi.model = F, na.fill = T, - ncores = NULL) +Calibration(exp, obs, cal.method = "mse_min", eval.method = "leave-one-out", + multi.model = F, na.fill = T, ncores = 1) } \arguments{ -\item{exp}{an array containing the seasonal forecast experiment data in the element named \code{$data}.} +\item{exp}{an array containing the seasonal forecast experiment data.} -\item{obs}{an array containing the observed data in the element named \code{$data}.} +\item{obs}{an array containing the observed data.} \item{cal.method}{is the calibration method used, can be either \code{bias}, \code{evmos}, \code{mse_min} or \code{crps_min}. Default value is \code{mse_min}.} @@ -21,16 +20,21 @@ Calibration(exp, obs, cal.method = "mse_min", \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{ncores}{is an integer that indicates the number of cores for parallel computations using multiApply function.} +\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 of the exp data. +an array containing the calibrated forecasts with the same dimensions as the \code{exp} array. } \description{ Four 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). Both in-sample or our out-of-sample (leave-one-out cross validation) calibration are possible. } +\author{ +Verónica Torralba, \email{veronica.torralba@bsc.es} + +Bert Van Schaeybroeck, \email{bertvs@meteo.be} +} \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 @@ -41,8 +45,4 @@ Van Schaeybroeck, B., & Vannitsem, S. (2015). Ensemble post-processing using mem \seealso{ \code{\link{CST_Load}} } -\author{ -Verónica Torralba, \email{veronica.torralba@bsc.es} -Bert Van Schaeybroeck, \email{bertvs@meteo.be} -} diff --git a/man/EnsClustering.Rd b/man/EnsClustering.Rd index d7284ef5..27aca453 100644 --- a/man/EnsClustering.Rd +++ b/man/EnsClustering.Rd @@ -67,3 +67,4 @@ Paolo Davini - ISAC-CNR, \email{p.davini@isac.cnr.it} Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} } + diff --git a/man/MultiEOF.Rd b/man/MultiEOF.Rd index c38116de..1e822fc4 100644 --- a/man/MultiEOF.Rd +++ b/man/MultiEOF.Rd @@ -46,3 +46,4 @@ Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} Paolo Davini - ISAC-CNR, \email{p.davini@isac.cnr.it} } + diff --git a/man/PlotCombinedMap.Rd b/man/PlotCombinedMap.Rd index 62e26904..6857c64d 100644 --- a/man/PlotCombinedMap.Rd +++ b/man/PlotCombinedMap.Rd @@ -5,10 +5,10 @@ \title{Plot Multiple Lon-Lat Variables In a Single Map According to a Decision Function} \usage{ PlotCombinedMap(maps, lon, lat, map_select_fun, display_range, - map_dim = "map", brks = NULL, cols = NULL, - col_unknown_map = "white", mask = NULL, col_mask = "grey", - bar_titles = NULL, legend_scale = 1, fileout = NULL, width = 8, - height = 5, size_units = "in", res = 100, ...) + map_dim = "map", brks = NULL, cols = NULL, col_unknown_map = "white", + mask = NULL, col_mask = "grey", bar_titles = NULL, legend_scale = 1, + fileout = NULL, width = 8, height = 5, size_units = "in", res = 100, + ...) } \arguments{ \item{maps}{List of matrices to plot, each with (longitude, latitude) dimensions, or 3-dimensional array with the dimensions (longitude, latitude, map). Dimension names are required.} @@ -67,11 +67,12 @@ PlotCombinedMap(list(a, b, c), lons, lats, bar_titles = paste('\% of belonging to', c('a', 'b', 'c')), brks = 20, width = 10, height = 8) } -\seealso{ -\code{PlotCombinedMap} and \code{PlotEquiMap} -} \author{ Nicolau Manubens, \email{nicolau.manubens@bsc.es} Veronica Torralba, \email{veronica.torralba@bsc.es} } +\seealso{ +\code{PlotCombinedMap} and \code{PlotEquiMap} +} + diff --git a/man/PlotForecastPDF.Rd b/man/PlotForecastPDF.Rd index 3eee4e33..d7b95b08 100644 --- a/man/PlotForecastPDF.Rd +++ b/man/PlotForecastPDF.Rd @@ -4,11 +4,10 @@ \alias{PlotForecastPDF} \title{Plot one or multiple ensemble forecast pdfs for the same event} \usage{ -PlotForecastPDF(fcst, tercile.limits, extreme.limits = NULL, - obs = NULL, plotfile = NULL, title = "Set a title", - var.name = "Varname (units)", fcst.names = NULL, - add.ensmemb = c("above", "below", "no"), color.set = c("ggplot", - "s2s4e", "hydro")) +PlotForecastPDF(fcst, tercile.limits, extreme.limits = NULL, obs = NULL, + plotfile = NULL, title = "Set a title", var.name = "Varname (units)", + fcst.names = NULL, add.ensmemb = c("above", "below", "no"), + color.set = c("ggplot", "s2s4e", "hydro")) } \arguments{ \item{fcst}{a dataframe or array containing all the ensember members for each forecast. If \code{'fcst'} is an array, it should have two labelled dimensions, and one of them should be \code{'members'}. If \code{'fcsts'} is a data.frame, each column shoul be a separate forecast, with the rows beeing the different ensemble members.} @@ -50,3 +49,4 @@ PlotForecastPDF(fcsts2, c(-0.66, 0.66), extreme.limits = c(-1.2, 1.2), \author{ Llorenç Lledó \email{llledo@bsc.es} } + diff --git a/man/PlotMostLikelyQuantileMap.Rd b/man/PlotMostLikelyQuantileMap.Rd index 0d984ede..6c92850e 100644 --- a/man/PlotMostLikelyQuantileMap.Rd +++ b/man/PlotMostLikelyQuantileMap.Rd @@ -109,10 +109,11 @@ PlotMostLikelyQuantileMap(bins, lons, lats, mask = 1 - (w1 + w2 / max(c(w1, w2))), brks = 20, width = 10, height = 8) -} -\seealso{ -\code{PlotCombinedMap} and \code{PlotEquiMap} } \author{ Veronica Torralba, \email{veronica.torralba@bsc.es}, Nicolau Manubens, \email{nicolau.manubens@bsc.es} } +\seealso{ +\code{PlotCombinedMap} and \code{PlotEquiMap} +} + diff --git a/man/RFSlope.Rd b/man/RFSlope.Rd index 5308ef8c..09a24ff5 100644 --- a/man/RFSlope.Rd +++ b/man/RFSlope.Rd @@ -60,3 +60,4 @@ slopes \author{ Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} } + diff --git a/man/RainFARM.Rd b/man/RainFARM.Rd index e0fa9a10..984dcd42 100644 --- a/man/RainFARM.Rd +++ b/man/RainFARM.Rd @@ -4,10 +4,10 @@ \alias{RainFARM} \title{RainFARM stochastic precipitation downscaling (reduced version)} \usage{ -RainFARM(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", - drop_realization_dim = FALSE, verbose = FALSE) +RainFARM(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", drop_realization_dim = FALSE, + verbose = FALSE) } \arguments{ \item{data}{Precipitation array to downscale. @@ -117,3 +117,4 @@ dim(res$data) \author{ Jost von Hardenberg - ISAC-CNR, \email{j.vonhardenberg@isac.cnr.it} } + diff --git a/man/SplitDim.Rd b/man/SplitDim.Rd index f07e4756..e36aa8a5 100644 --- a/man/SplitDim.Rd +++ b/man/SplitDim.Rd @@ -35,3 +35,4 @@ new_data <- SplitDim(data, indices = time, freq = 'year') \author{ Nuria Perez-Zanon, \email{nuria.perez@bsc.es} } + diff --git a/man/areave_data.Rd b/man/areave_data.Rd index a772220a..cc79c85c 100644 --- a/man/areave_data.Rd +++ b/man/areave_data.Rd @@ -41,3 +41,4 @@ areave_data <- Nicolau Manubens \email{nicolau.manubens@bsc.es} } \keyword{data} + diff --git a/man/as.s2dv_cube.Rd b/man/as.s2dv_cube.Rd index c2b8f3a8..13a2a296 100644 --- a/man/as.s2dv_cube.Rd +++ b/man/as.s2dv_cube.Rd @@ -40,11 +40,12 @@ data <- as.s2dv_cube(data) class(data) } } -\seealso{ -\code{\link{s2dv_cube}}, \code{\link[s2dverification]{Load}}, \code{\link[startR]{Start}} and \code{\link{CST_Load}} -} \author{ Perez-Zanon Nuria, \email{nuria.perez@bsc.es} Nicolau Manubens, \email{nicolau.manubens@bsc.es} } +\seealso{ +\code{\link{s2dv_cube}}, \code{\link[s2dverification]{Load}}, \code{\link[startR]{Start}} and \code{\link{CST_Load}} +} + diff --git a/man/lonlat_data.Rd b/man/lonlat_data.Rd index 0c6ee30f..eca7abac 100644 --- a/man/lonlat_data.Rd +++ b/man/lonlat_data.Rd @@ -41,3 +41,4 @@ lonlat_data <- Nicolau Manubens \email{nicolau.manubens@bsc.es} } \keyword{data} + diff --git a/man/lonlat_prec.Rd b/man/lonlat_prec.Rd index 345e3cab..69cb94e8 100644 --- a/man/lonlat_prec.Rd +++ b/man/lonlat_prec.Rd @@ -29,3 +29,4 @@ lonlat_prec <- CST_Load('prlr', exp = list(infile), obs = NULL, Jost von Hardenberg \email{j.vonhardenberg@isac.cnr.it} } \keyword{data} + diff --git a/man/s2dv_cube.Rd b/man/s2dv_cube.Rd index f57d5ed3..48af7bbb 100644 --- a/man/s2dv_cube.Rd +++ b/man/s2dv_cube.Rd @@ -75,9 +75,10 @@ exp8 <- s2dv_cube(data = exp_original, lon = seq(-10, 10, 5), lat = c(45, 50), end = paste0(rep("31", 10), rep("01", 10), 1990:1999))) class(exp8) } -\seealso{ -\code{\link[s2dverification]{Load}} and \code{\link{CST_Load}} -} \author{ Perez-Zanon Nuria, \email{nuria.perez@bsc.es} } +\seealso{ +\code{\link[s2dverification]{Load}} and \code{\link{CST_Load}} +} + -- GitLab