diff --git a/DESCRIPTION b/DESCRIPTION index 2cb6f17e9a939c77e5f74706db509c3b78098a49..9123c589b1411638ea21e364a1592dc7be137f30 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: CSTools Title: Assessing Skill of Climate Forecasts on Seasonal-to-Decadal Timescales -Version: 4.1.0 +Version: 4.1.1 Authors@R: c( person("Nuria", "Perez-Zanon", , "nuria.perez@bsc.es", role = "aut", comment = c(ORCID = "0000-0001-8568-3071")), person("Louis-Philippe", "Caron", , "louis-philippe.caron@bsc.es", role = "aut", comment = c(ORCID = "0000-0001-5221-0147")), diff --git a/NEWS.md b/NEWS.md index b1403786ad0eb1193f366ce3f5dbd61114ebcc74..72362e9bbbc6092b81aca5a1a95d0ce1428ffffd 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,10 @@ +### CSTools 4.1.1 +**Submission date to CRAN: 10-11-2022** +- Fixes: + + CST_Analogs corrected input of ClimProjDiags::Subset() + + PlotCombinedMap corrected use of 'cex_bar_titles' parameter + + CST_Anomaly added 'memb_dim', 'dat_dim' and 'ftime_dim' and improved use for 'dim_anom' parameters + ### CSTools 4.1.0 **Submission date to CRAN: 25-10-2022** - New features: diff --git a/R/CST_Analogs.R b/R/CST_Analogs.R index 78da4022a27db19d7079f105da1585f2c5db7987..6437868091a5b8c9e4f9731dc32953ffbcee159a 100644 --- a/R/CST_Analogs.R +++ b/R/CST_Analogs.R @@ -130,7 +130,7 @@ CST_Analogs <- function(expL, obsL, expVar = NULL, obsVar = NULL, region = NULL, criteria = 'Large_dist', excludeTime = NULL, time_expL = NULL, time_obsL = NULL, nAnalogs = NULL, AnalogsInfo = FALSE, - ncores = 1) { + ncores = NULL) { if (!inherits(expL, "s2dv_cube") || !inherits(obsL, "s2dv_cube")) { stop("Parameter 'expL' and 'obsL' must be of the class 's2dv_cube', ", "as output by CSTools::CST_Load.") diff --git a/man/Analogs.Rd b/man/Analogs.Rd index fc26a5523fe0dd78c4755b03f106118d99b193b3..a7addc73e5bf4936c06e29be410841aae5519619 100644 --- a/man/Analogs.Rd +++ b/man/Analogs.Rd @@ -20,56 +20,56 @@ Analogs( region = NULL, nAnalogs = NULL, AnalogsInfo = FALSE, - ncores = 1 + ncores = NULL ) } \arguments{ -\item{expL}{an array of N named dimensions containing the experimental field +\item{expL}{An array of N named dimensions containing the experimental field on the large scale for which the analog is aimed. This field is used to in all the criterias. If parameter 'expVar' is not provided, the function will return the expL analog. The element 'data' in the 's2dv_cube' object must -have, at least, latitudinal and longitudinal dimensions. The object is expect -to be already subset for the desired large scale region.} +have, at least, latitudinal and longitudinal dimensions. The object is +expect to be already subset for the desired large scale region.} -\item{obsL}{an array of N named dimensions containing the observational field +\item{obsL}{An array of N named dimensions containing the observational field on the large scale. The element 'data' in the 's2dv_cube' object must have 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 +\item{time_obsL}{A character string indicating the date of the observations in the format "dd/mm/yyyy". Reference time to search for analogs.} -\item{time_expL}{an array of N named dimensions (coinciding with time +\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.} -\item{lonL}{a vector containing the longitude of parameter 'expL'.} +\item{lonL}{A vector containing the longitude of parameter 'expL'.} -\item{latL}{a vector containing the latitude of parameter 'expL'.} +\item{latL}{A vector containing the latitude of parameter 'expL'.} -\item{expVar}{an array of N named dimensions containing the experimental +\item{expVar}{An array of N named dimensions containing the experimental field on the local scale, usually a different variable to the parameter 'expL'. If it is not NULL (by default, NULL), the returned field by this function will be the analog of parameter 'expVar'.} -\item{obsVar}{an array of N named dimensions containing the field of the +\item{obsVar}{An array of N named dimensions containing the field of the same variable as the passed in parameter 'expVar' for the same region.} \item{criteria}{a character string indicating the criteria to be used for the selection of analogs: -\itemize{ -\item{Large_dist} minimum Euclidean distance in the large scale pattern; -\item{Local_dist} minimum Euclidean distance in the large scale pattern -and minimum Euclidean distance in the local scale pattern; and -\item{Local_cor} minimum Euclidean distance in the large scale pattern, -minimum Euclidean distance in the local scale pattern and highest -correlation in the local variable to downscale.}} - -\item{excludeTime}{an array of N named dimensions (coinciding with time + \itemize{\item{Large_dist} minimum Euclidean distance in the large scale pattern; + \item{Local_dist} minimum Euclidean distance in the large scale pattern + and minimum Euclidean distance in the local scale pattern; and + \item{Local_cor} minimum Euclidean distance in the large scale pattern, + minimum Euclidean distance in the local scale pattern and highest + correlation in the local variable to downscale.}} + +\item{excludeTime}{An array of N named dimensions (coinciding with time dimensions in expL) of character string(s) indicating the date(s) of the observations in the format "dd/mm/yyyy" to be excluded during the search of -analogs. It can be NULL but if expL is not a forecast (time_expL contained in -time_obsL),by default time_expL will be removed during the search of analogs.} +analogs. It can be NULL but if expL is not a forecast (time_expL contained +in time_obsL), by default time_expL will be removed during the search of +analogs.} \item{lonVar}{a vector containing the longitude of parameter 'expVar'.} @@ -88,23 +88,25 @@ NULL for 'Local_dist' and 'Local_cor' the default value will be set at the length of 'time_obsL'. If AnalogsInfo is FALSE the function returns just the best analog.} -\item{AnalogsInfo}{TRUE to get a list with two elements: 1) the downscaled -field and 2) the AnalogsInfo which contains: a) the number of the best +\item{AnalogsInfo}{A logical value. If it is TRUE it returns a list +with two elements: 1) the downscaled field and +2) the AnalogsInfo which contains: a) the number of the best analogs, b) the corresponding value of the metric used in the selected criteria (distance values for Large_dist and Local_dist,correlation values -for Local_cor), c)dates of the analogs). The analogs are listed in decreasing -order, the first one is the best analog (i.e if the selected criteria is -Local_cor the best analog will be the one with highest correlation, while for -Large_dist criteria the best analog will be the day with minimum Euclidean -distance). Set to FALSE to get a single analog, the best analog, for instance -for downscaling.} +for Local_cor), c)dates of the analogs). The analogs are listed in +decreasing order, the first one is the best analog (i.e if the selected +criteria is Local_cor the best analog will be the one with highest +correlation, while for Large_dist criteria the best analog will be the day +with minimum Euclidean distance). Set to FALSE to get a single analog, the +best analog, for instance for downscaling.} \item{ncores}{the number of cores to use in parallel computation.} } \value{ -AnalogsFields, dowscaled values of the best analogs for the criteria -selected. If AnalogsInfo is set to TRUE the function also returns a -list with the dowsncaled field and the Analogs Information. +An array with the dowscaled values of the best analogs for the criteria +selected. If 'AnalogsInfo' is set to TRUE it returns a list with an array +of the dowsncaled field and the analogs information in elements 'analogs', +'metric' and 'dates'. } \description{ This function perform a downscaling using Analogs. To compute @@ -156,7 +158,7 @@ downscale_field <- Analogs(expL = expSLP, obsL = obsSLP, obsVar = obs.pr, obsSLP <- c(rnorm(1:1980), expSLP * 1.5) dim(obsSLP) <- c(lat = 4, lon = 5, time = 100) time_obsSLP <- paste(rep("01", 100), rep("01", 100), 1920 : 2019, sep = "-") -downscale_field<- Analogs(expL = expSLP, obsL = obsSLP, time_obsSLP, +downscale_field <- Analogs(expL = expSLP, obsL = obsSLP, time_obsSLP, nAnalogs = 5, time_expL = "01-01-2003", AnalogsInfo = TRUE, excludeTime = "01-01-2003") @@ -170,7 +172,7 @@ downscale_field <- Analogs(expL = expSLP, obsL = obsSLP, obsVar = obs.pr, # Example 5: Downscaling using criteria 'Local_dist' and 2 variables: # analogs of local scale using criteria 2 -region=c(lonmin = -1 ,lonmax = 2, latmin = 30, latmax = 33) +region = c(lonmin = -1 ,lonmax = 2, latmin = 30, latmax = 33) Local_scale <- Analogs(expL = expSLP, obsL = obsSLP, time_obsL = time_obsSLP, obsVar = obs.pr, criteria = "Local_dist", lonL = seq(-1, 5, 1.5),latL = seq(30, 35, 1.5), diff --git a/man/CST_Analogs.Rd b/man/CST_Analogs.Rd index 7a67b0fb2facf261acb5e28f91321ecdcee816ba..b0242f584023df4d157937e7f92d4c972791fa9e 100644 --- a/man/CST_Analogs.Rd +++ b/man/CST_Analogs.Rd @@ -16,34 +16,34 @@ CST_Analogs( time_obsL = NULL, nAnalogs = NULL, AnalogsInfo = FALSE, - ncores = 1 + ncores = NULL ) } \arguments{ -\item{expL}{an 's2dv_cube' object containing the experimental field on the +\item{expL}{An 's2dv_cube' object containing the experimental field on the large scale for which the analog is aimed. This field is used to in all the criterias. If parameter 'expVar' is not provided, the function will return the expL analog. The element 'data' in the 's2dv_cube' object must have, at least, latitudinal and longitudinal dimensions. The object is expect to be already subset for the desired large scale region.} -\item{obsL}{an 's2dv_cube' object containing the observational field on the +\item{obsL}{An 's2dv_cube' object containing the observational field on the large scale. The element 'data' in the 's2dv_cube' object must have the same latitudinal and longitudinal dimensions as parameter 'expL' and a temporal dimension with the maximum number of available observations.} -\item{expVar}{an 's2dv_cube' object containing the experimental field on the +\item{expVar}{An 's2dv_cube' object containing the experimental field on the local scale, usually a different variable to the parameter 'expL'. If it is not NULL (by default, NULL), the returned field by this function will be the analog of parameter 'expVar'.} -\item{obsVar}{an 's2dv_cube' containing the field of the same variable as the +\item{obsVar}{An 's2dv_cube' containing the field of the same variable as the passed in parameter 'expVar' for the same region.} -\item{region}{a vector of length four indicating the minimum longitude, +\item{region}{A vector of length four indicating the minimum longitude, the maximum longitude, the minimum latitude and the maximum latitude.} -\item{criteria}{a character string indicating the criteria to be used for the +\item{criteria}{A character string indicating the criteria to be used for the selection of analogs: \itemize{ \item{Large_dist} minimum Euclidean distance in the large scale pattern; @@ -55,21 +55,21 @@ correlation in the local variable to downscale.} Criteria 'Large_dist' is recommended for CST_Analogs, for an advanced use of the criterias 'Local_dist' and 'Local_cor' use 'Analogs' function.} -\item{excludeTime}{an array of N named dimensions (coinciding with time +\item{excludeTime}{An array of N named dimensions (coinciding with time dimensions in expL)of character string(s) indicating the date(s) of the observations in the format "dd/mm/yyyy" to be excluded during the search of analogs. It can be NULL but if expL is not a forecast (time_expL contained in time_obsL), by default time_expL will be removed during the search of analogs.} -\item{time_expL}{a character string indicating the date of the experiment +\item{time_expL}{A character string indicating the date of the experiment in the same format than time_obsL (i.e. "yyyy-mm-dd"). By default it is NULL and dates are taken from element \code{$Dates$start} from expL.} -\item{time_obsL}{a character string indicating the date of the observations +\item{time_obsL}{A character string indicating the date of the observations in the date format (i.e. "yyyy-mm-dd"). By default it is NULL and dates are taken from element \code{$Dates$start} from obsL.} -\item{nAnalogs}{number of Analogs to be selected to apply the criterias +\item{nAnalogs}{Number of Analogs to be selected to apply the criterias 'Local_dist' or 'Local_cor'. This is not the necessary the number of analogs that the user can get, but the number of events with minimum distance in which perform the search of the best Analog. The default value for the @@ -79,22 +79,24 @@ NULL for 'Local_dist' and 'Local_cor' the default value will be set at the length of 'time_obsL'. If AnalogsInfo is FALSE the function returns just the best analog.} -\item{AnalogsInfo}{TRUE to get a list with two elements: 1) the downscaled -field and 2) the AnalogsInfo which contains: a) the number of the best -analogs, b) the corresponding value of the metric used in the selected -criteria (distance values for Large_dist and Local_dist,correlation values -for Local_cor), c)dates of the analogs). The analogs are listed in decreasing -order, the first one is the best analog (i.e if the selected criteria is -Local_cor the best analog will be the one with highest correlation, while for -Large_dist criteria the best analog will be the day with minimum Euclidean -distance). Set to FALSE to get a single analog, the best analog, for instance -for downscaling.} +\item{AnalogsInfo}{A logical value. TRUE to get a list with two elements: +1) the downscaled field and 2) the AnalogsInfo which contains: +a) the number of the best analogs, b) the corresponding value of the metric +used in the selected criteria (distance values for Large_dist and Local_dist, +correlation values for Local_cor), c)dates of the analogs). The analogs are +listed in decreasing order, the first one is the best analog (i.e if the +selected criteria is Local_cor the best analog will be the one with highest +correlation, while for Large_dist criteria the best analog will be the day +with minimum Euclidean distance). Set to FALSE to get a single analog, the +best analog, for instance for downscaling.} \item{ncores}{The number of cores to use in parallel computation} } \value{ -An 'array' object containing the dowscaled values of the best -analogs. +An 's2dv_cube' object containing an array with the dowscaled values of +the best analogs in element 'data'. If 'AnalogsInfo' is TRUE, 'data' is a list +with an array of the downscaled fields and the analogs information in +elements 'analogs', 'metric' and 'dates'. } \description{ This function perform a downscaling using Analogs. To compute @@ -124,10 +126,10 @@ function within 'CSTools' package. } \examples{ expL <- rnorm(1:200) -dim(expL) <- c(member=10,lat = 4, lon = 5) +dim(expL) <- c(member = 10,lat = 4, lon = 5) obsL <- c(rnorm(1:180),expL[1,,]*1.2) dim(obsL) <- c(time = 10,lat = 4, lon = 5) -time_obsL <- paste(rep("01", 10), rep("01", 10), 1994 : 2003, sep = "-") +time_obsL <- paste(rep("01", 10), rep("01", 10), 1994:2003, sep = "-") time_expL <- time_obsL[1] lon <- seq(-1,5,1.5) lat <- seq(30,35,1.5) @@ -137,6 +139,7 @@ obsL <- s2dv_cube(data = obsL, lat = lat, lon = lon, Dates = list(start = time_obsL, end = time_obsL)) region <- c(min(lon), max(lon), min(lat), max(lat)) downscaled_field <- CST_Analogs(expL = expL, obsL = obsL, region = region) + } \references{ Yiou, P., T. Salameh, P. Drobinski, L. Menut, R. Vautard, diff --git a/vignettes/WeatherRegimes_vignette.Rmd b/vignettes/WeatherRegimes_vignette.Rmd index 47d095ce6d424a07a9ce8ee627b1e245d9366eef..788b25761eaac40a729cd90132b2d2abf5335a23 100644 --- a/vignettes/WeatherRegimes_vignette.Rmd +++ b/vignettes/WeatherRegimes_vignette.Rmd @@ -30,7 +30,7 @@ library(zeallot) The data employed in this example are described below. - Sea level pressure (psl): this has been selected as the circulation variable, however other variables such as geopotential at 500 hPa can be also used. - Region: Euro-Atlantic domain [85.5ºW-45ºE; 27-81ºN]. -- Datasets: seasonal predictions from ECMWF System 4 ([**Molteni et al. 2011**] (https://www.ecmwf.int/sites/default/files/elibrary/2011/11209-new-ecmwf-seasonal-forecast-system-system-4.pdf)) and ERA-Interim reanalysis ([**Dee et al. 2011**] (https://rmets.onlinelibrary.wiley.com/doi/pdf/10.1002/qj.828)) as a reference dataset. +- Datasets: seasonal predictions from ECMWF System 4 ([**Molteni et al. 2011**](https://www.ecmwf.int/sites/default/files/elibrary/2011/11209-new-ecmwf-seasonal-forecast-system-system-4.pdf)) and ERA-Interim reanalysis ([**Dee et al. 2011**](https://doi.org/10.1002/qj.828)) as a reference dataset. - Period: 1991-2010. Only 20 years have been selected for illustrative purposes, but the full hindcast period could be used for the analysis. @@ -75,7 +75,7 @@ The LOESS filter has been applied to the climatology to remove the short-term va ### 4- Weather regimes in observations -`CST_WeatherRegimes()` function is used to define the clusters based on the sea level pressure anomalies from ERA-Interim. This function is based on the [*kmeans function*] (https://stat.ethz.ch/R-manual/R-devel/library/stats/html/kmeans.html) +`CST_WeatherRegimes()` function is used to define the clusters based on the sea level pressure anomalies from ERA-Interim. This function is based on the [*kmeans function*](https://stat.ethz.ch/R-manual/R-devel/library/stats/html/kmeans.html) from the stats R package. In this example we have made different assumptions: four clusters (`ncenters=4`) will be produced and the Empirical orthogonal functions are not used to filter the data (`EOFS=FALSE`) just to take into account the extreme values. More details about the methodology can be found in Cortesi et al. 2018 (submitted).