diff --git a/.Rbuildignore b/.Rbuildignore index 5493f6df42b306fd00555b902681e895fd4c2925..aa8227b142f77c731283cc23cb40abe0e7fdc490 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -8,3 +8,4 @@ README\.Rmd$ README\.md$ \..*\.RData$ vignettes +.gitlab-ci.yml diff --git a/DESCRIPTION b/DESCRIPTION index 99c08ff66547282a64f34fe3ea1cfedc161aa28a..78935b854eb76f5ab7dce4fe18216a6c0588ccde 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -4,7 +4,9 @@ Version: 2.8.5 Authors@R: c( person("BSC-CNS", role = c("aut", "cph")), person("Virginie", "Guemas", , "virginie.guemas@bsc.es", role = "aut"), - person("Nicolau", "Manubens", , "nicolau.manubens@bsc.es", role = c("aut", "cre")), + person("Nicolau", "Manubens", , "nicolau.manubens@bsc.es", role = "aut"), + person("An-Chi", "Ho", , "an.ho@bsc.es", role = c("ctb", "cre")), + person("Nuria", "Perez-Zanon", , "nuria.perez@bsc.es", role = "ctb"), person("Javier", "Garcia-Serrano", , "javier.garcia@bsc.es", role = "aut"), person("Neven", "Fuckar", , "neven.fuckar@bsc.es", role = "aut"), person("Louis-Philippe", "Caron", , "louis-philippe.caron@bsc.es", role = "aut"), @@ -26,9 +28,14 @@ Authors@R: c( person("Eleftheria", "Exarchou", , "eleftheria.exarchou@bsc.es", role = "ctb"), person("Ruben", "Cruz", , "ruben.cruzgarcia@bsc.es", role = "ctb"), person("Isabel", "Andreu-Burillo", , "isabel.andreu.burillo@ic3.cat", role = "ctb"), - person("Ramiro", "Saurral", , "ramiro.saurral@ic3.cat", role = "ctb"), - person("An-Chi", "Ho", , "an.ho@bsc.es", role = "ctb")) -Description: Set of tools to verify forecasts through the computation of typical prediction scores against one or more observational datasets or reanalyses (a reanalysis being a physical extrapolation of observations that relies on the equations from a model, not a pure observational dataset). Intended for seasonal to decadal climate forecasts although can be useful to verify other kinds of forecasts. The package can be helpful in climate sciences for other purposes than forecasting. + person("Ramiro", "Saurral", , "ramiro.saurral@ic3.cat", role = "ctb")) +Description: Set of tools to verify forecasts through the computation of typical + prediction scores against one or more observational datasets or reanalyses (a + reanalysis being a physical extrapolation of observations that relies on the + equations from a model, not a pure observational dataset). Intended for seasonal + to decadal climate forecasts although can be useful to verify other kinds of + forecasts. The package can be helpful in climate sciences for other purposes + than forecasting. Depends: maps, methods, @@ -53,3 +60,4 @@ BugReports: https://earth.bsc.es/gitlab/es/s2dverification/issues LazyData: true SystemRequirements: cdo Encoding: UTF-8 +RoxygenNote: 5.0.0 diff --git a/NAMESPACE b/NAMESPACE index 7c49d6b922c72886c92321ca8d9002b490735a91..3e35710e2d54618b5a2311a1a03f839de76e59f3 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,2 +1,133 @@ -exportPattern("^[^\\.]") -import(abind, bigmemory, GEOmap, geomapdata, graphics, grDevices, mapproj, maps, methods, NbClust, ncdf4, parallel, plyr, stats, SpecsVerification) +# Generated by roxygen2: do not edit by hand + +export(.BrierScore) +export(.Corr) +export(.RMS) +export(.RMSSS) +export(.RatioRMS) +export(.RatioSDRMS) +export(.Trend) +export(ACC) +export(Alpha) +export(AnimateMap) +export(Ano) +export(Ano_CrossValid) +export(ArrayToNetCDF) +export(BrierScore) +export(CDORemap) +export(Clim) +export(Cluster) +export(ColorBar) +export(Composite) +export(ConfigAddEntry) +export(ConfigApplyMatchingEntries) +export(ConfigEditDefinition) +export(ConfigEditEntry) +export(ConfigFileCreate) +export(ConfigFileOpen) +export(ConfigFileSave) +export(ConfigRemoveDefinition) +export(ConfigRemoveEntry) +export(ConfigShowDefinitions) +export(ConfigShowSimilarEntries) +export(ConfigShowTable) +export(Consist_Trend) +export(Corr) +export(EOF) +export(Enlarge) +export(Eno) +export(EnoNew) +export(Filter) +export(FitAcfCoef) +export(FitAutocor) +export(GenSeries) +export(Histo2Hindcast) +export(IniListDims) +export(InsertDim) +export(LeapYear) +export(Load) +export(Mean1Dim) +export(MeanListDim) +export(NAO) +export(Plot2VarsVsLTime) +export(PlotACC) +export(PlotAno) +export(PlotBoxWhisker) +export(PlotClim) +export(PlotEquiMap) +export(PlotLayout) +export(PlotSection) +export(PlotStereoMap) +export(PlotVsLTime) +export(ProbBins) +export(ProjectField) +export(RMS) +export(RMSSS) +export(RatioRMS) +export(RatioSDRMS) +export(Regression) +export(SVD) +export(Season) +export(SelIndices) +export(Smoothing) +export(Spectrum) +export(Spread) +export(StatSeasAtlHurr) +export(Subset) +export(ToyModel) +export(Trend) +export(UltimateBrier) +export(clim.colors) +export(clim.palette) +import(GEOmap) +import(NbClust) +import(SpecsVerification) +import(abind) +import(bigmemory) +import(geomapdata) +import(graphics) +import(mapproj) +import(maps) +import(methods) +import(ncdf4) +import(parallel) +import(plyr) +importFrom(grDevices,bmp) +importFrom(grDevices,col2rgb) +importFrom(grDevices,colorRampPalette) +importFrom(grDevices,dev.cur) +importFrom(grDevices,dev.new) +importFrom(grDevices,dev.off) +importFrom(grDevices,gray) +importFrom(grDevices,jpeg) +importFrom(grDevices,pdf) +importFrom(grDevices,png) +importFrom(grDevices,postscript) +importFrom(grDevices,rainbow) +importFrom(grDevices,rgb) +importFrom(grDevices,svg) +importFrom(grDevices,tiff) +importFrom(stats,IQR) +importFrom(stats,acf) +importFrom(stats,confint) +importFrom(stats,cor) +importFrom(stats,kmeans) +importFrom(stats,lm) +importFrom(stats,mad) +importFrom(stats,median) +importFrom(stats,na.omit) +importFrom(stats,na.pass) +importFrom(stats,pf) +importFrom(stats,predict) +importFrom(stats,pt) +importFrom(stats,qchisq) +importFrom(stats,qnorm) +importFrom(stats,qt) +importFrom(stats,quantile) +importFrom(stats,rnorm) +importFrom(stats,runif) +importFrom(stats,sd) +importFrom(stats,setNames) +importFrom(stats,spectrum) +importFrom(stats,ts) +importFrom(stats,window) diff --git a/NEWS.md b/NEWS.md new file mode 100644 index 0000000000000000000000000000000000000000..51b198b1aa2272eb0830ff43f2626d207b821ddf --- /dev/null +++ b/NEWS.md @@ -0,0 +1,3 @@ +# s2dverification 2.9.0 (Release date: ) +- Apply Roxygen2 to all the files. (2019.07.31) (An-Chi) + diff --git a/R/ACC.R b/R/ACC.R index 8c1210dce8cd01c3198d324dd5535c89c3d63f80..aeabc0796950d180691a8e4fc6abd5c5e5309c59 100644 --- a/R/ACC.R +++ b/R/ACC.R @@ -1,3 +1,98 @@ +#'Computes Anomaly Correlation Coefficient +#' +#'Calculates the Anomaly Correlation Coefficient for the ensemble mean of +#'each model and the corresponding references for each startdate and each +#'leadtime.\cr +#'The domain of interest can be specified by providing the list +#'of longitudes/latitudes (lon/lat) of the grid together with the corners +#'of the domain:\cr +#' lonlatbox = c(lonmin, lonmax, latmin, latmax). +#' +#'@param var_exp Array of experimental anomalies with dimensions: +#' c(nexp, nsdates, nltimes, nlat, nlon) or +#' c(nexp, nsdates, nmembers, nltimes, nlat, nlon). +#'@param var_obs Array of observational anomalies, same dimensions as var_exp +#' except along the first dimension and the second if it corresponds to the +#' member dimension. +#'@param lon Array of longitudes of the var_exp/var_obs grids, optional. +#'@param lat Array of latitudes of the var_exp/var_obs grids, optional. +#'@param lonlatbox Domain to select: c(lonmin, lonmax, latmin, latmax), +#' optional. +#'@param conf TRUE/FALSE: confidence intervals and significance level +#' provided or not. +#'@param conftype "Parametric" provides a confidence interval for the ACC +#' computed by a Fisher transformation and a significance level for the ACC +#' from a one-sided student-T distribution. "Bootstrap" provides a confidence +#' interval for the ACC and MACC computed from bootstrapping on the members +#' with 100 drawings with replacement. To guarantee the statistical robustness +#' of the result, make sure that your experiments/oservations/startdates/ +#' leadtimes always have the same number of members. +#'@param siglev The confidence level for the computed confidence intervals. +#' +#'@return +#'\item{ACC}{ +#' If \code{conf = TRUE}, array with dimensions: +#' c(nexp, nobs, nsdates, nleadtimes, 4) +#' The fifth dimension of length 4 corresponds to the lower limit of the +#' \code{siglev}\% confidence interval, the ACC, the upper limit of the +#' \code{siglev}\% confidence interval and the \code{siglev}\% significance +#' level. If \code{conf = FALSE}, the array of the Anomaly Correlation +#' Coefficient has dimensions c(nexp, nobs, nsdates, nleadtimes). +#'} +#'\item{MACC}{ +#' The array of the Mean Anomaly Correlation Coefficient with dimensions +#' c(nexp, nobs, nleadtimes). +#'} +#' +#'@examples +#'# See ?Load for explanations on the first part of this example. +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' leadtimemin = 1, leadtimemax = 4, output = 'lonlat', +#' latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' leadtimemin = 1, +#' leadtimemax = 4, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'sampleData$mod <- Season(sampleData$mod, 4, 11, 12, 2) +#'sampleData$obs <- Season(sampleData$obs, 4, 11, 12, 2) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'ano_exp <- Ano(sampleData$mod, clim$clim_exp) +#'ano_obs <- Ano(sampleData$obs, clim$clim_obs) +#'acc <- ACC(Mean1Dim(ano_exp, 2), Mean1Dim(ano_obs, 2)) +#'PlotACC(acc$ACC, startDates) +#'@references Joliffe and Stephenson (2012). Forecast Verification: A +#' Practitioner's Guide in Atmospheric Science. Wiley-Blackwell. +#'@keywords datagen +#'@author +#'History:\cr +#' 0.1 - 2013-08 (V. Guemas, \email{virginie.guemas@@bsc.es}) - Original code\cr +#' 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@bsc.es}) - Formatting to CRAN\cr +#' 1.1 - 2013-09 (C. Prodhomme, \email{chloe.prodhomme@@bsc.es}) - optimization\cr +#' 1.2 - 2014-08 (V. Guemas, \email{virginie.guemas@@bsc.es}) - Bug-fixes: handling of NA & selection of domain + Simplification of code\cr +#' 1.3.0 - 2014-08 (V. Guemas, \email{virginie.guemas@@bsc.es}) - Boostrapping over members\cr +#' 1.3.1 - 2014-09 (C. Prodhomme, \email{chloe.prodhomme@@bsc.es}) - Add comments and minor style changes\cr +#' 1.3.2 - 2015-02 (N. Manubens, \email{nicolau.manubens@@bsc.es}) - Fixed ACC documentation and examples +#'@import abind +#'@importFrom stats qt qnorm quantile +#'@export ACC <- function(var_exp, var_obs, lon = NULL, lat = NULL, lonlatbox = NULL, conf = TRUE, conftype = "parametric", siglev = 0.95) { diff --git a/R/Alpha.R b/R/Alpha.R index c5b68f6f879090ef685b7aad82bfcd3497533190..a1ef1f0c42b4ae59b55f0fb7e465dc59709b6e93 100644 --- a/R/Alpha.R +++ b/R/Alpha.R @@ -1,3 +1,34 @@ +#'Estimates AutoCorrelation At Lag 1 following Guemas et al, BAMS, 2013b +#' +#'This function, relying on the \code{FitAcfCoef()} function, estimates the +#'autocorrelation at lag 1 of the xdata array following the method described +#'in Guemas V., Auger L., Doblas-Reyes F., JAMC, 2013. After applying a linear +#'detrending and/or a filtering of any frequency peak if requested, the sample +#'autocorrelation is estimated.\cr +#'Then the theoretical autocorrelation of an AR1 is fitted to the sample +#'autocorrelation using the Cardano's formula (see \code{FitAcfCoef()}) to +#'obtain the autocorrelation at lag 1. This method assumes xdata is an AR1 +#'process. +#'@param xdata Timeseries from which the autocorrelation at lag 1 is requested. +#'@param detrend TRUE applies a linear detrending to xdata prior to the +#' estimation of the autocorrelation at lag 1. +#'@param filter TRUE applies a filtering of any frequency peak prior to the +#' estimation of the autocorrelation at lag 1. +#' +#'@return Autocorrelation at lag 1. +#' +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'alpha <- Alpha(sampleData$mod[1, 1, , 1]) +#'print(alpha) +#' +#'@keywords datagen +#'@author History:\cr +#' 0.1 - 2012-06 (V. Guemas, \email{virginie.guemas@@ic3.cat}) - Original code\cr +#' 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to CRAN +#'@importFrom stats lm confint acf +#'@export Alpha <- function(xdata, detrend = FALSE, filter = FALSE) { tmp <- xdata diff --git a/R/AnimateMap.R b/R/AnimateMap.R index 86ca0bffe84e764ac25a47d1b475dac67d05462a..0f4d4b38d50731a796d329c20aeaaeb19577090b 100644 --- a/R/AnimateMap.R +++ b/R/AnimateMap.R @@ -1,3 +1,160 @@ +#'Animate Maps of Forecast/Observed Values or Scores Over Forecast Time +#' +#'Create animations of maps in an equi-rectangular or stereographic +#'projection, showing the anomalies, the climatologies, the mean InterQuartile +#'Range, Maximum-Mininum, Standard Deviation, Median Absolute Deviation, +#'the trends, the RMSE, the correlation or the RMSSS, between modelled and +#'observed data along the forecast time (lead-time) for all input experiments +#'and input observational datasets. +#' +#'@param var Matrix of dimensions (nltime, nlat, nlon) or +#' (nexp/nmod, nltime, nlat, nlon) or (nexp/nmod, 3/4, nltime, nlat, nlon) or +#' (nexp/nmod, nobs, 3/4, nltime, nlat, nlon). +#'@param lon Vector containing longtitudes (degrees). +#'@param lat Vector containing latitudes (degrees). +#'@param toptitle c('','', \dots) array of main title for each animation, +#' optional. If RMS, RMSSS, correlations: first exp with successive obs, then +#' second exp with successive obs, etc ... +#'@param sizetit Multiplicative factor to increase title size, optional. +#'@param units Units, optional. +#'@param monini Starting month between 1 and 12. Default = 1. +#'@param freq 1 = yearly, 12 = monthly, 4 = seasonal ... +#'@param msk95lev TRUE/FALSE grid points with dots if 95\% significance level +#' reached. Default = FALSE. +#'@param brks Limits of colour levels, optional. For example: +#' seq(min(var), max(var), (max(var) - min(var)) / 10). +#'@param cols Vector of colours of length(brks) - 1, optional. +#'@param filled.continents Continents filled in grey (TRUE) or represented by +#' a black line (FALSE). Default = TRUE. Filling unavailable if crossing +#' Greenwich and equi = TRUE. Filling unavailable if square = FALSE and +#' equi = TRUE. +#'@param lonmin Westward limit of the domain to plot (> 0 or < 0). +#' Default : 0 degrees. +#'@param lonmax Eastward limit of the domain to plot (> 0 or < 0). +#' lonmax > lonmin. Default : 360 degrees. +#'@param latmin Southward limit of the domain to plot. Default : -90 degrees. +#'@param latmax Northward limit of the domain to plot. Default : 90 degrees. +#'@param intlat Interval between latitude ticks on y-axis for equi = TRUE or +#' between latitude circles for equi = FALSE. Default = 30 degrees. +#'@param intlon Interval between longitude ticks on x-axis. +#' Default = 20 degrees. +#'@param drawleg Draw a colorbar. Can be FALSE only if square = FALSE or +#' equi = FALSE. Default = TRUE. +#'@param subsampleg Supsampling factor of the interval between ticks on +#' colorbar. Default = 1 = every colour level. +#'@param colNA Color used to represent NA. Default = 'white'. +#'@param equi TRUE/FALSE == cylindrical equidistant/stereographic projection. +#' Default: TRUE. +#'@param fileout c('', '', \dots) array of output file name for each animation. +#' If RMS, RMSSS, correlations : first exp with successive obs, then second +#' exp with successive obs, etc ... +#'@param ... Arguments to be passed to the method. Only accepts the following +#' graphical parameters:\cr +#' adj ann ask bty cex cex.axis cex.lab cex.main cex.sub +#' cin col.axis col.lab col.main col.sub cra crt csi cxy err family fg fig +#' font font.axis font.lab font.main font.sub las lheight ljoin lmitre lty +#' lwd mai mar mex mfcol mfrow mfg mgp mkh oma omd omi page pch plt pty smo +#' srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog. \cr +#' For more information about the parameters see `par`. +#' +#'@details +#'Examples of input: +#'\enumerate{ +#' \item{ +#' Outputs from clim (exp, obs, memb = FALSE): +#' (nmod, nltime, nlat, nlon) +#' or (nobs, nltime, nlat, nlon) +#' } +#' \item{ +#' Model output from load/ano/smoothing: +#' (nmod, nmemb, sdate, nltime, nlat, nlon) +#' then passed through spread(var, posdim = 2, narm = TRUE) +#' & mean1dim(var, posdim = 3, narm = TRUE) +#' or through trend(mean1dim(var, 2), posTR = 2): +#' (nmod, 3, nltime, nlat, nlon) +#' animates average along start dates of IQR/MaxMin/SD/MAD across members +#' or trends of the ensemble-mean computed accross the start dates. +#' } +#' \item{ +#' model and observed output from load/ano/smoothing: +#' (nmod, nmemb, sdate, nltime, nlat, nlon) +#' & (nobs, nmemb, sdate, nltime, nlat, nlon) +#' then averaged along members mean1dim(var_exp/var_obs, posdim = 2): +#' (nmod, sdate, nltime, nlat, nlon) +#' (nobs, sdate, nltime, nlat, nlon) +#' then passed through corr(exp, obs, posloop = 1, poscor = 2) +#' or RMS(exp, obs, posloop = 1, posRMS = 2): +#' (nmod, nobs, 3, nltime, nlat, nlon) +#' animates correlations or RMS between each exp & each obs against leadtime. +#' } +#'} +#' +#'@keywords dynamic +#'@author History:\cr +#' 1.0 - 2012-04 (V. Guemas, \email{virginie.guemas@@bsc.es}) - Original code\cr +#' 1.1 - 2014-04 (N. Manubens, \email{nicolau.manubens@@bsc.es}) - Formatting to CRAN\cr +#' 1.2 - 2015-05 (V. Guemas, \email{virginie.guemas@@bsc.es}) - Use of PlotEquiMap and PlotStereoMap +#' +#'@examples +#'# See ?Load for explanations on the first part of this example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' output = 'lonlat', latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'clim <- Clim(sampleData$mod, sampleData$obs, memb = FALSE) +#' \dontrun{ +#'AnimateMap(clim$clim_exp, sampleData$lon, sampleData$lat, +#' toptitle = "climatology of decadal prediction", sizetit = 1, +#' units = "degree", brks = seq(270, 300, 3), monini = 11, freq = 12, +#' msk95lev = FALSE, filled.continents = TRUE, intlon = 10, intlat = 10, +#' fileout = 'clim_dec.gif') +#' } +#'ano_exp <- Ano(sampleData$mod, clim$clim_exp) +#'ano_obs <- Ano(sampleData$obs, clim$clim_obs) +#'leadtimes_dimension <- 4 +#'initial_month <- 11 +#'mean_start_month <- 1 +#'mean_stop_month <- 12 +#'season_means_mod <- Season(ano_exp, leadtimes_dimension, initial_month, +#' mean_start_month, mean_stop_month) +#'season_means_obs <- Season(ano_obs, leadtimes_dimension, initial_month, +#' mean_start_month, mean_stop_month) +#' \dontrun{ +#'AnimateMap(Mean1Dim(season_means_mod, 2)[1, 1, , , ], sampleData$lon, +#' sampleData$lat, toptitle = "Annual anomalies 1985 of decadal prediction", +#' sizetit = 1, units = "degree", monini = 1, freq = 1, msk95lev = FALSE, +#' brks = seq(-0.5, 0.5, 0.1), intlon = 10, intlat = 10, +#' filled.continents = TRUE, fileout = 'annual_means_dec.gif') +#' } +#'dim_to_mean <- 2 # Mean along members +#'rms <- RMS(Mean1Dim(season_means_mod, dim_to_mean), +#' Mean1Dim(season_means_obs, dim_to_mean)) +#'AnimateMap(rms, sampleData$lon, sampleData$lat, toptitle = +#' "RMSE decadal prediction", sizetit = 1, units = "degree", +#' monini = 1, freq = 1, msk95lev = FALSE, brks = seq(0, 0.8, 0.08), +#' intlon = 10, intlat = 10, filled.continents = TRUE, +#' fileout = 'rmse_dec.gif') +#'@importFrom grDevices postscript dev.off +#'@export AnimateMap <- function(var, lon, lat, toptitle = rep("", 11), sizetit = 1, units = "", monini = 1, freq = 12, msk95lev = FALSE, brks = NULL, cols = NULL, filled.continents = FALSE, diff --git a/R/Ano.R b/R/Ano.R index ed3350a24b6cd382125f2df6d4306fd42251f40a..657e7f9b8816f00680c6d337f5ca84872833ce24 100644 --- a/R/Ano.R +++ b/R/Ano.R @@ -1,3 +1,40 @@ +#'Computes Forecast or Observed Anomalies +#' +#'This function computes anomalies from any experimental or observational +#'matrix output from \code{Load()} and their climatologies output from +#'\code{Clim()}. +#' +#'@param var Model or observational data:\cr +#' c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltime) up to \cr +#' c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon)\cr +#'@param clim Climatologies from clim: c(nmod/nexp/nobs, nltime) \cr +#' up to c(nmod/nexp/nobs, nltime, nlevel, nlat, nlon) or \cr +#' c(nmod/nexp/nobs, nmemb/nparam, nltime) up to \cr +#' c(nmod/nexp/nobs, nmemb/nparam, nltime, nlevel, nlat, nlon) or \cr +#' c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltime) up to \cr +#' c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon) \cr +#' depending on the options provided to \code{Clim()}. +#' +#'@return Array with same dimensions as 'var'. +#'@keywords datagen +#'@author History:\cr +#' 0.1 - 2012-03 (V. Guemas, \email{virginie.guemas@@ic3.cat}) - Original code\cr +#' 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to R CRAN +#' +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'ano_exp <- Ano(sampleData$mod, clim$clim_exp) +#'ano_obs <- Ano(sampleData$obs, clim$clim_obs) +#'runmean_nb_months <- 12 +#'dim_to_smooth <- 4 # Smooth along lead-times +#'smooth_ano_exp <- Smoothing(ano_exp, runmean_nb_months, dim_to_smooth) +#'smooth_ano_obs <- Smoothing(ano_obs, runmean_nb_months, dim_to_smooth) +#'PlotAno(smooth_ano_exp, smooth_ano_obs, startDates, +#' toptitle = paste('smoothed anomalies'), ytitle = c('K', 'K', 'K'), +#' legends = 'ERSST', biglab = FALSE, fileout = 'tos_ano.eps') +#'@export Ano <- function(var, clim) { # # Duplicate clim dimensions to heve same dimensions as var diff --git a/R/Ano_CrossValid.R b/R/Ano_CrossValid.R index a0727d147c5662a5b75fe19e8eba6160547ad872..e42941f256f3fcb85859c430d64317c56bc43e66 100644 --- a/R/Ano_CrossValid.R +++ b/R/Ano_CrossValid.R @@ -1,3 +1,35 @@ +#'Computes Anomalies In Cross-Validation Mode +#' +#'Computes the anomalies from the arrays of the experimental and observational +#'data output from \code{load()} by subtracting the climatologies computed +#'with a cross-validation technique and a per-pair method. +#' +#'@param var_exp Model data:\cr +#'c(nmod/nexp, nmemb/nparam, nsdates, nltime) up to \cr +#' c(nmod/nexp, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon). +#'@param var_obs Observational data: \cr +#'c(nobs, nmemb, nsdates, nltime) up to \cr +#' c(nobs, nmemb, nsdates, nltime, nlevel, nlat, nlon). +#'@param memb TRUE/FALSE (1 climatology for each member/1 climatology +#' averaging all the members). Default = TRUE. +#' +#'@return +#' \item{$ano_exp}{Matrix with same dimensions as var_exp} +#' \item{$ano_obs}{Matrix with same dimensions as var_obs} +#' +#'@keywords datagen +#'@author History:\cr +#' 0.1 - 2011-12 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +#' 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to CRAN +#' +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'anomalies <- Ano_CrossValid(sampleData$mod, sampleData$obs) +#'PlotAno(anomalies$ano_exp, anomalies$ano_obs, startDates, +#' toptitle = paste('anomalies'), ytitle = c('K', 'K', 'K'), +#' legends = 'ERSST', biglab = FALSE, fileout = 'tos_ano_crossvalid.eps') +#'@export Ano_CrossValid <- function(var_exp, var_obs, memb = TRUE) { # # Enlarge the number of dimensions of var_exp and var_obs to 7 if necessary diff --git a/R/ArrayToNetCDF.R b/R/ArrayToNetCDF.R index 47fe13ef20ee9003cc937210915f820277411dea..298a5706b37e3d7a4d9a2c003f860b59aaa77471 100644 --- a/R/ArrayToNetCDF.R +++ b/R/ArrayToNetCDF.R @@ -1,3 +1,232 @@ +#'Save multidimensional R arrays into NetCDF files +#' +#'This function takes as input one or a list of multidimensional R arrays and +#'stores them in a NetCDF file, using the \code{ncdf4} package. The full path +#'and name of the resulting file must be specified. Metadata can be attached +#'to the arrays and propagated into the NetCDF file in 3 possible ways: +#'\itemize{ +#' \item{ +#' Via the list names if a list of arrays is provided: Each name in +#' the input list, corresponding to one multidimensional array, will be +#' interpreted as the name of the variable it contains.\cr +#' E.g:\cr +#' \code{ArrayToNetCDF(arrays = list(temperature = array(1:9, c(3, 3))),}\cr +#' \code{ file_path = 'example.nc')} +#' } +#' \item{ +#' Via the dimension names of each provided array: The dimension names +#' of each of the provided arrays will be interpreted as names for the +#' dimensions of the NetCDF files. Read further for special dimension names +#' that will trigger special behaviours, such as 'time' and 'var'.\cr +#' E.g:\cr +#' \code{temperature <- array(rnorm(100 * 50 * 10), dim = c(100, 50, 10))}\cr +#' \code{names(dim(temperature)) <- c('longitude', 'latitude', 'time')}\cr +#' \code{ArrayToNetCDF(list(temperature = temperature), file_path = 'example.nc')} +#' } +#' \item{ +#' Via the attribute 'variables' of each provided array: The arrays can +#' be provided with metadata in an attribute named 'variables', which is +#' expected to be a named list of named lists, where the names of the +#' container list are the names of the variables present in the provided +#' array, and where each sub-list contains metadata for each of the variables. +#' The attribute names and values supported in the sub-lists must follow the +#' same format the package \code{ncdf4} uses to represent the NetCDF +#' file headers.\cr +#' E.g:\cr +#' \code{a <- array(1:400, dim = c(5, 10, 4, 2))}\cr +#' \code{metadata <- list(tos = list(addOffset = 100,}\cr +#' \code{ scaleFact = 10,}\cr +#' \code{ dim = list(list(name = 'time',}\cr +#' \code{ unlim = FALSE))))}\cr +#' \code{attr(a, 'variables') <- metadata}\cr +#' \code{names(dim(a)) <- c('lat', 'lon', 'time', 'var')}\cr +#' \code{ArrayToNetCDF(a, 'tmp.nc')} +#' } +#'} +#'The special dimension names are 'var'/'variable' and 'time'.\cr +#'If a dimension is named 'var' or 'variable', \code{ArrayToNetCDF} will +#'interpret each array entry along such dimension corresponds to a separate +#'new variable, hence will create a new variable inside the NetCDF file and +#'will use it to store all the data in the provided array for the +#'corresponding entry along the 'var'/'variable' dimension.\cr +#'If a dimension is named 'time', by default it will be interpreted and built +#'as an unlimited dimension. The 'time' dimension must be the last dimension +#'of the array (the right-most). If a 'var'/'variable' dimension is present, +#'the 'time' dimension can be also placed on its left (i.e. the one before the +#'last dimension). The default behaviour of creating the 'time' as unlimited +#'dimension can be disabled by setting manually the attribute +#'\code{unlim = FALSE}, as shown in the previous example. +#' +#'@param arrays One or a list of multidimensional data arrays. The list can be +#' provided with names, which will be interpreted as variable names. The +#' arrays can be provided with dimension names. The arrays can be provided +#' with metadata in the attribute 'variables' (read section Description for +#' details). +#'@param file_path Path and name of the NetCDF file to be created. +#' +#'@return This function returns NULL. +#'@keywords datagen +#'@author History:\cr +#' 0.0 - 2017-01 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Original code. +#' +#'@examples +#' \dontrun{ +#'# Minimal use case +#'ArrayToNetCDF(array(1:9, c(3, 3)), 'tmp.nc') +#' +#'# Works with arrays of any number of dimensions +#'ArrayToNetCDF(array(1:27, c(3, 3, 3)), 'tmp.nc') +#' +#'# Arrays can also be provided in [named] lists +#'ArrayToNetCDF(list(tos = array(1:27, c(3, 3, 3))), 'tmp.nc') +#' +#'# Or with dimension names +#'# 'var' dimension name will generate multiple variables in the +#'# resulting NetCDF file +#'a <- array(1:27, dim = c(3, 3, 3)) +#'names(dim(a)) <- c('lon', 'lat', 'var') +#'ArrayToNetCDF(a, 'tmp.nc') +#' +#'# 'variable' as dimension name will do the same +#'a <- array(1:27, dim = c(3, 3, 3)) +#'names(dim(a)) <- c('lon', 'lat', 'variable') +#'ArrayToNetCDF(a, 'tmp.nc') +#' +#'# The 'time' dimension will be built as unlimited dimension, by default +#'a <- array(1:1600, dim = c(10, 20, 4, 2)) +#'names(dim(a)) <- c('lat', 'lon', 'time', 'var') +#'ArrayToNetCDF(a, 'tmp.nc') +#' +#'# Putting the 'time' dimension in a position which is not the last, or the one +#'# right before 'var'/'variable' will crash. Unlimited dimension must be in the +#'# last position +#'a <- array(1:1600, dim = c(10, 20, 4, 2)) +#'names(dim(a)) <- c('time', 'lat', 'lon', 'var') +#'ArrayToNetCDF(a, 'tmp.nc') +#'a <- array(1:1600, dim = c(10, 20, 4, 2)) +#'names(dim(a)) <- c('lat', 'time', 'lon', 'var') +#'ArrayToNetCDF(a, 'tmp.nc') +#' +#'# The dimension 'var'/'variable' can be in any position and can have any length +#'a <- array(1:1600, dim = c(10, 20, 4, 2)) +#'names(dim(a)) <- c('lat', 'var', 'lon', 'time') +#'ArrayToNetCDF(a, 'tmp.nc') +#' +#'# Multiple arrays can be provided in a list +#'a <- array(1:400, dim = c(5, 10, 4, 2)) +#'names(dim(a)) <- c('lat', 'lon', 'time', 'var') +#'ArrayToNetCDF(list(a, a), 'tmp.nc') +#' +#'# If no dimension names are given to an array, new names will be automatically +#'# generated +#'a <- array(1:400, dim = c(5, 10, 4, 2)) +#'b <- array(1:400, dim = c(5, 11, 4, 2)) +#'names(dim(a)) <- c('lat', 'lon', 'time', 'var') +#'ArrayToNetCDF(list(a, b), 'tmp.nc') +#' +#'# If two arrays use a same dimension but their lengths differ, the function +#'# will crash +#'a <- array(1:400, dim = c(5, 10, 4, 2)) +#'b <- array(1:400, dim = c(5, 11, 4, 2)) +#'names(dim(a)) <- c('lat', 'lon', 'time', 'var') +#'names(dim(b)) <- c('lat', 'lon', 'time', 'var') +#'ArrayToNetCDF(list(a, b), 'tmp.nc') +#' +#'# Metadata can be provided for each variable in each array, via the +#'# attribute 'variables'. In this example the metadata is empty. +#'a <- array(1:400, dim = c(5, 10, 4, 2)) +#'metadata <- list( +#' tos = list(), +#' tas = list() +#' ) +#'attr(a, 'variables') <- metadata +#'names(dim(a)) <- c('lat', 'lon', 'time', 'var') +#'ArrayToNetCDF(a, 'tmp.nc') +#' +#'# Variable names can be manually specified +#'a <- array(1:400, dim = c(5, 10, 4, 2)) +#'metadata <- list( +#' tos = list(name = 'name1'), +#' tas = list(name = 'name2') +#' ) +#'attr(a, 'variables') <- metadata +#'names(dim(a)) <- c('lat', 'lon', 'time', 'var') +#'ArrayToNetCDF(a, 'tmp.nc') +#' +#'# Units can be specified +#'a <- array(1:400, dim = c(5, 10, 4, 2)) +#'metadata <- list( +#' tos = list(units = 'K'), +#' tas = list(units = 'K') +#' ) +#'attr(a, 'variables') <- metadata +#'names(dim(a)) <- c('lat', 'lon', 'time', 'var') +#'ArrayToNetCDF(a, 'tmp.nc') +#' +#'# addOffset and scaleFactor can be specified +#'a <- array(1:400, dim = c(5, 10, 4, 2)) +#'metadata <- list( +#' tos = list(addOffset = 100, +#' scaleFact = 10), +#' tas = list(addOffset = 100, +#' scaleFact = 10) +#' ) +#'attr(a, 'variables') <- metadata +#'names(dim(a)) <- c('lat', 'lon', 'time', 'var') +#'ArrayToNetCDF(a, 'tmp.nc') +#' +#'# Unlimited dimensions can be manually created +#'a <- array(1:400, dim = c(5, 10, 4, 2)) +#'metadata <- list( +#' tos = list(addOffset = 100, +#' scaleFact = 10, +#' dim = list(list(name = 'unlimited', +#' unlim = TRUE))), +#' tas = list(addOffset = 100, +#' scaleFact = 10, +#' dim = list(list(name = 'unlimited', +#' unlim = TRUE))) +#' ) +#'attr(a, 'variables') <- metadata +#'names(dim(a)) <- c('lat', 'lon', 'unlimited', 'var') +#'ArrayToNetCDF(a, 'tmp.nc') +#' +#'# A 'time' dimension can be built without it necessarily being unlimited +#'a <- array(1:400, dim = c(5, 10, 4, 2)) +#'metadata <- list( +#' tos = list(addOffset = 100, +#' scaleFact = 10, +#' dim = list(list(name = 'time', +#' unlim = FALSE))), +#' tas = list(addOffset = 100, +#' scaleFact = 10, +#' dim = list(list(name = 'time', +#' unlim = FALSE))) +#' ) +#'attr(a, 'variables') <- metadata +#'names(dim(a)) <- c('lat', 'lon', 'time', 'var') +#'ArrayToNetCDF(a, 'tmp.nc') +#' +#'# Multiple arrays with data for multiple variables can be saved into a +#'# NetCDF file at once. +#'tos <- array(1:400, dim = c(5, 10, 4)) +#'metadata <- list(tos = list(units = 'K')) +#'attr(tos, 'variables') <- metadata +#'names(dim(tos)) <- c('lat', 'lon', 'time') +#'lon <- seq(0, 360 - 360 / 10, length.out = 10) +#'dim(lon) <- length(lon) +#'metadata <- list(lon = list(units = 'degrees_east')) +#'attr(lon, 'variables') <- metadata +#'names(dim(lon)) <- 'lon' +#'lat <- seq(-90, 90, length.out = 5) +#'dim(lat) <- length(lat) +#'metadata <- list(lat = list(units = 'degrees_north')) +#'attr(lat, 'variables') <- metadata +#'names(dim(lat)) <- 'lat' +#'ArrayToNetCDF(list(tos, lon, lat), 'tmp.nc') +#'} +#'@import ncdf4 +#'@export ArrayToNetCDF <- function(arrays, file_path) { # Check parameter arrays. if (is.array(arrays)) { diff --git a/R/BrierScore.R b/R/BrierScore.R index e1b01bcf7afc64e6e163a20c0131797dba2fb144..ec92263060803579ccb8060600cdd66d1a64a373 100644 --- a/R/BrierScore.R +++ b/R/BrierScore.R @@ -1,3 +1,88 @@ +#'Compute Brier Score And Its Decomposition And Brier Skill Score +#' +#'Computes the Brier score (BS) and the components of its standard +#'decomposition as well with the two within-bin components described in +#'Stephenson et al., (2008). It also returns the bias-corrected decomposition +#'of the BS (Ferro and Fricker, 2012). BSS having the climatology as the +#'reference forecast. \cr\cr +#'.BrierScore provides the same functionality, but taking a matrix of ensemble +#'members (exp) as input. +#' +#'@param obs Vector of binary observations (1 or 0). +#'@param pred Vector of probablistic predictions with values in the range [0,1]. +#'@param thresholds Values used to bin the forecasts. By default the bins are +#' {[0,0.1), [0.1, 0.2), ... [0.9, 1]}. +#'@param exp Matrix of predictions with values in the range [0,1] for the +#' .BrierScore function +#' +#'@return Both BrierScore and .Brier score provide the same outputs: +#'\itemize{ +#' \item{$rel}{standard reliability} +#' \item{$res}{standard resolution} +#' \item{$unc}{standard uncertainty} +#' \item{$bs}{Brier score} +#' \item{$bs_check_res}{rel-res+unc} +#' \item{$bss_res}{res-rel/unc} +#' \item{$gres}{generalized resolution} +#' \item{$bs_check_gres}{rel-gres+unc} +#' \item{$bss_gres}{gres-rel/unc} +#' \item{$rel_bias_corrected}{bias-corrected rel} +#' \item{$gres_bias_corrected}{bias-corrected gres} +#' \item{$unc_bias_corrected}{bias-corrected unc} +#' \item{$bss_bias_corrected}{gres_bias_corrected-rel_bias_corrected/unc_bias_corrected} +#' \item{$nk}{number of forecast in each bin} +#' \item{$fkbar}{average probability of each bin} +#' \item{$okbar}{relative frequency that the observed event occurred} +#' \item{$bins}{bins used} +#' \item{$pred}{values with which the forecasts are verified} +#' \item{$obs}{probability forecasts of the event} +#'} +#' +#'@references +#'Wilks (2006) Statistical Methods in the Atmospheric Sciences.\cr +#'Stephenson et al. (2008). Two extra components in the Brier score decomposition. +#' Weather and Forecasting, 23: 752-757.\cr +#'Ferro and Fricker (2012). A bias-corrected decomposition of the BS. +#' Quarterly Journal of the Royal Meteorological Society, DOI: 10.1002/qj.1924. +#' +#'@keywords datagen +#'@author History:\cr +#' 0.1 - 2012-04 (L. Rodrigues, \email{lrodrigues@@ic3.cat}) - Original code\cr +#' 0.2 - 2017-02 (A. Hunter, \email{alasdair.hunter@@bsc.es}) - Adapted to veriApply() +#' +#'@examples +#'# Minimalist examples with BrierScore +#'a <- runif(10) +#'b <- round(a) +#'x <- BrierScore(b, a) +#'x$bs - x$bs_check_res +#'x$bs - x$bs_check_gres +#'x$rel_bias_corrected - x$gres_bias_corrected + x$unc_bias_corrected +#' \dontrun{ +#'a <- runif(10) +#'b <- cbind(round(a),round(a)) # matrix containing 2 identical ensemble members... +#'x2 <- BrierScore(a, b) +#' } +#' +#'# Example of BrierScore using UltimateBrier +#'# See ?UltimateBrier for more information +#'example(Load) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'ano_exp <- Ano(sampleData$mod, clim$clim_exp) +#'ano_obs <- Ano(sampleData$obs, clim$clim_obs) +#'bs <- UltimateBrier(ano_exp, ano_obs, thr = c(1/3, 2/3)) +#' +#' \dontrun{ +#'# Example of .BrierScore with veriApply +#'require(easyVerification) +#'BrierScore2 <- s2dverification:::.BrierScore +#'bins_ano_exp <- ProbBins(ano_exp, thr = c(1/3, 2/3), posdates = 3, posdim = 2) +#'bins_ano_obs <- ProbBins(ano_obs, thr = c(1/3, 2/3), posdates = 3, posdim = 2) +#'bs2 <- veriApply("BrierScore2", bins_ano_exp, Mean1Dim(bins_ano_ob,s 3), +#' tdim = 2, ensdim = 3) +#' } +#'@rdname BrierScore +#'@export BrierScore <- function(obs, pred, thresholds = seq(0, 1, 0.1)) { if (max(pred) > 1 | min(pred) < 0) { stop("Predictions outside [0,1] range. Are you certain this is a probability forecast? \n") @@ -73,7 +158,8 @@ BrierScore <- function(obs, pred, thresholds = seq(0, 1, 0.1)) { } } - +#'@rdname BrierScore +#'@export .BrierScore <- function(exp, obs, thresholds = seq(0, 1, 0.1)) { if (max(exp) > 1 || min(exp) < 0) { stop("Parameter 'exp' contains predictions outside [0,1] range. Are you certain this is a probability forecast?") diff --git a/R/CDORemap.R b/R/CDORemap.R index 88c2cd42187cf84d6b1d99bd58ffd6b10554ddc3..a04d88a536447a2488283d5e5c3991d079490012 100644 --- a/R/CDORemap.R +++ b/R/CDORemap.R @@ -1,3 +1,212 @@ +#'Interpolates arrays with longitude and latitude dimensions using CDO +#' +#'This function takes as inputs a multidimensional array (optional), a vector +#'or matrix of longitudes, a vector or matrix of latitudes, a destination grid +#'specification, and the name of a method to be used to interpolate (one of +#'those available in the 'remap' utility in CDO). The interpolated array is +#'returned (if provided) together with the new longitudes and latitudes.\cr\cr +#'\code{CDORemap()} permutes by default the dimensions of the input array (if +#'needed), splits it in chunks (CDO can work with data arrays of up to 4 +#'dimensions), generates a file with the data of each chunk, interpolates it +#'with CDO, reads it back into R and merges it into a result array. If no +#'input array is provided, the longitude and latitude vectors will be +#'transformed only. If the array is already on the desired destination grid, +#'no transformation is performed (this behvaiour works only for lonlat and +#'gaussian grids). \cr\cr +#'Any metadata attached to the input data array, longitudes or latitudes will +#'be preserved or accordingly modified. +#' +#'@param data_array Multidimensional numeric array to be interpolated. If +#' provided, it must have at least a longitude and a latitude dimensions, +#' identified by the array dimension names. The names for these dimensions +#' must be one of the recognized by s2dverification (can be checked with +#' \code{s2dverification:::.KnownLonNames()} and +#' \code{s2dverification:::.KnownLatNames()}). +#'@param lons Numeric vector or array of longitudes of the centers of the grid +#' cells. Its size must match the size of the longitude/latitude dimensions +#' of the input array. +#'@param lats Numeric vector or array of latitudes of the centers of the grid +#' cells. Its size must match the size of the longitude/latitude dimensions +#' of the input array. +#'@param grid Character string specifying either a name of a target grid +#' (recognized by CDO; e.g.: 'r256x128', 't106grid') or a path to another +#' NetCDF file which to read the target grid from (a single grid must be +#' defined in such file). +#'@param method Character string specifying an interpolation method +#' (recognized by CDO; e.g.: 'con', 'bil', 'bic', 'dis'). The following +#' long names are also supported: 'conservative', 'bilinear', 'bicubic' and +#' 'distance-weighted'. +#'@param avoid_writes The step of permutation is needed when the input array +#' has more than 3 dimensions and none of the longitude or latitude dimensions +#' in the right-most position (CDO would not accept it without permuting +#' previously). This step, executed by default when needed, can be avoided +#' for the price of writing more intermediate files (whis usually is +#' unconvenient) by setting the parameter \code{avoid_writes = TRUE}. +#'@param crop Whether to crop the data after interpolation with +#' 'cdo sellonlatbox' (TRUE) or to extend interpolated data to the whole +#' world as CDO does by default (FALSE). If \code{crop = TRUE} then the +#' longitude and latitude borders which to crop at are taken as the limits of +#' the cells at the borders ('lons' and 'lats' are perceived as cell centers), +#' i.e. the resulting array will contain data that covers the same area as +#' the input array. This is equivalent to specifying \code{crop = 'preserve'}, +#' i.e. preserving area. If \code{crop = 'tight'} then the borders which to +#' crop at are taken as the minimum and maximum cell centers in 'lons' and +#' 'lats', i.e. the area covered by the resulting array may be smaller if +#' interpolating from a coarse grid to a fine grid. The parameter 'crop' also +#' accepts a numeric vector of custom borders which to crop at: +#' c(western border, eastern border, southern border, northern border). +#'@param force_remap Whether to force remapping, even if the input data array +#' is already on the target grid. +#'@param write_dir Path to the directory where to create the intermediate +#' files for CDO to work. By default, the R session temporary directory is +#' used (\code{tempdir()}). +#' +#'@return A list with the following components: +#' \item{'data_array'}{The interpolated data array (if an input array +#' is provided at all, NULL otherwise).} +#' \item{'lons'}{The longitudes of the data on the destination grid.} +#' \item{'lats'}{The latitudes of the data on the destination grid.} +#'@keywords datagen +#'@author History:\cr +#' 0.0 - 2017-01 (N. Manubens, \email{nicolau.manubens@@bsc.es}) - Original code. +#'@examples +#' \dontrun{ +#'# Interpolating only vectors of longitudes and latitudes +#'lon <- seq(0, 360 - 360/50, length.out = 50) +#'lat <- seq(-90, 90, length.out = 25) +#'tas2 <- CDORemap(NULL, lon, lat, 't170grid', 'bil', TRUE) +#' +#'# Minimal array interpolation +#'tas <- array(1:50, dim = c(25, 50)) +#'names(dim(tas)) <- c('lat', 'lon') +#'lon <- seq(0, 360 - 360/50, length.out = 50) +#'lat <- seq(-90, 90, length.out = 25) +#'tas2 <- CDORemap(tas, lon, lat, 't170grid', 'bil', TRUE) +#' +#'# Metadata can be attached to the inputs. It will be preserved and +#'# accordignly modified. +#'tas <- array(1:50, dim = c(25, 50)) +#'names(dim(tas)) <- c('lat', 'lon') +#'lon <- seq(0, 360 - 360/50, length.out = 50) +#'metadata <- list(lon = list(units = 'degrees_east')) +#'attr(lon, 'variables') <- metadata +#'lat <- seq(-90, 90, length.out = 25) +#'metadata <- list(lat = list(units = 'degrees_north')) +#'attr(lat, 'variables') <- metadata +#'metadata <- list(tas = list(dim = list(lat = list(len = 25, +#' vals = lat), +#' lon = list(len = 50, +#' vals = lon) +#' ))) +#'attr(tas, 'variables') <- metadata +#'tas2 <- CDORemap(tas, lon, lat, 't170grid', 'bil', TRUE) +#' +#'# Arrays of any number of dimensions in any order can be provided. +#'num_lats <- 25 +#'num_lons <- 50 +#'tas <- array(1:(10*num_lats*10*num_lons*10), +#' dim = c(10, num_lats, 10, num_lons, 10)) +#'names(dim(tas)) <- c('a', 'lat', 'b', 'lon', 'c') +#'lon <- seq(0, 360 - 360/num_lons, length.out = num_lons) +#'metadata <- list(lon = list(units = 'degrees_east')) +#'attr(lon, 'variables') <- metadata +#'lat <- seq(-90, 90, length.out = num_lats) +#'metadata <- list(lat = list(units = 'degrees_north')) +#'attr(lat, 'variables') <- metadata +#'metadata <- list(tas = list(dim = list(a = list(), +#' lat = list(len = num_lats, +#' vals = lat), +#' b = list(), +#' lon = list(len = num_lons, +#' vals = lon), +#' c = list() +#' ))) +#'attr(tas, 'variables') <- metadata +#'tas2 <- CDORemap(tas, lon, lat, 't17grid', 'bil', TRUE) +#'# The step of permutation can be avoided but more intermediate file writes +#'# will be performed. +#'tas2 <- CDORemap(tas, lon, lat, 't17grid', 'bil', FALSE) +#' +#'# If the provided array has the longitude or latitude dimension in the +#'# right-most position, the same number of file writes will be performed, +#'# even if avoid_wrties = FALSE. +#'num_lats <- 25 +#'num_lons <- 50 +#'tas <- array(1:(10*num_lats*10*num_lons*10), +#' dim = c(10, num_lats, 10, num_lons)) +#'names(dim(tas)) <- c('a', 'lat', 'b', 'lon') +#'lon <- seq(0, 360 - 360/num_lons, length.out = num_lons) +#'metadata <- list(lon = list(units = 'degrees_east')) +#'attr(lon, 'variables') <- metadata +#'lat <- seq(-90, 90, length.out = num_lats) +#'metadata <- list(lat = list(units = 'degrees_north')) +#'attr(lat, 'variables') <- metadata +#'metadata <- list(tas = list(dim = list(a = list(), +#' lat = list(len = num_lats, +#' vals = lat), +#' b = list(), +#' lon = list(len = num_lons, +#' vals = lon) +#' ))) +#'attr(tas, 'variables') <- metadata +#'tas2 <- CDORemap(tas, lon, lat, 't17grid', 'bil', TRUE) +#'tas2 <- CDORemap(tas, lon, lat, 't17grid', 'bil', FALSE) +#' +#'# An example of an interpolation from and onto a rectangular regular grid +#'num_lats <- 25 +#'num_lons <- 50 +#'tas <- array(1:(1*num_lats*num_lons), dim = c(num_lats, num_lons)) +#'names(dim(tas)) <- c('y', 'x') +#'lon <- array(seq(0, 360 - 360/num_lons, length.out = num_lons), +#' dim = c(num_lons, num_lats)) +#'metadata <- list(lon = list(units = 'degrees_east')) +#'names(dim(lon)) <- c('x', 'y') +#'attr(lon, 'variables') <- metadata +#'lat <- t(array(seq(-90, 90, length.out = num_lats), +#' dim = c(num_lats, num_lons))) +#'metadata <- list(lat = list(units = 'degrees_north')) +#'names(dim(lat)) <- c('x', 'y') +#'attr(lat, 'variables') <- metadata +#'tas2 <- CDORemap(tas, lon, lat, 'r100x50', 'bil') +#' +#'# An example of an interpolation from an irregular grid onto a gaussian grid +#'num_lats <- 25 +#'num_lons <- 50 +#'tas <- array(1:(10*num_lats*10*num_lons*10), +#' dim = c(10, num_lats, 10, num_lons)) +#'names(dim(tas)) <- c('a', 'j', 'b', 'i') +#'lon <- array(seq(0, 360 - 360/num_lons, length.out = num_lons), +#' dim = c(num_lons, num_lats)) +#'metadata <- list(lon = list(units = 'degrees_east')) +#'names(dim(lon)) <- c('i', 'j') +#'attr(lon, 'variables') <- metadata +#'lat <- t(array(seq(-90, 90, length.out = num_lats), +#' dim = c(num_lats, num_lons))) +#'metadata <- list(lat = list(units = 'degrees_north')) +#'names(dim(lat)) <- c('i', 'j') +#'attr(lat, 'variables') <- metadata +#'tas2 <- CDORemap(tas, lon, lat, 't17grid', 'bil') +#' +#'# Again, the dimensions can be in any order +#'num_lats <- 25 +#'num_lons <- 50 +#'tas <- array(1:(10*num_lats*10*num_lons), +#' dim = c(10, num_lats, 10, num_lons)) +#'names(dim(tas)) <- c('a', 'j', 'b', 'i') +#'lon <- array(seq(0, 360 - 360/num_lons, length.out = num_lons), +#' dim = c(num_lons, num_lats)) +#'names(dim(lon)) <- c('i', 'j') +#'lat <- t(array(seq(-90, 90, length.out = num_lats), +#' dim = c(num_lats, num_lons))) +#'names(dim(lat)) <- c('i', 'j') +#'tas2 <- CDORemap(tas, lon, lat, 't17grid', 'bil') +#'tas2 <- CDORemap(tas, lon, lat, 't17grid', 'bil', FALSE) +#'# It is ossible to specify an external NetCDF file as target grid reference +#'tas2 <- CDORemap(tas, lon, lat, 'external_file.nc', 'bil') +#'} +#'@import ncdf4 +#'@importFrom stats lm predict setNames +#'@export CDORemap <- function(data_array = NULL, lons, lats, grid, method, avoid_writes = TRUE, crop = TRUE, force_remap = FALSE, write_dir = tempdir()) { #, mask = NULL) { diff --git a/R/Clim.R b/R/Clim.R index 4fdfa038f9ef4b5396870173f9d35346a914a9eb..8a390ad4a96b6f57821e094f57c47f759ff41d21 100644 --- a/R/Clim.R +++ b/R/Clim.R @@ -1,3 +1,51 @@ +#'Computes Bias Corrected Climatologies +#' +#'This function computes only per-pair climatologies from the experimental +#'and observational matrices output from \code{Load()}. +#'To compute plain climatologies from only experimental or observational +#'data from \code{Load()}, the following code can be used:\cr +#'\code{clim <- array(apply(obs_data, c(1, 4, 5, 6), mean),}\cr +#'\code{ dim = dim(obs_datta)[-c(2, 3)])}\cr +#'The function \code{Clim()} computes per-pair climatologies using one of the +#'following methods: +#'\enumerate{ +#' \item{per-pair method (Garcia-Serrano and Doblas-Reyes, CD, 2012)} +#' \item{Kharin method (Karin et al, GRL, 2012)} +#' \item{Fuckar method (Fuckar et al, GRL, 2014)} +#'} +#'\code{Clim()} computes climatologies using the startdates covered by the +#'whole experiments/observational data sets. The startdates not available for +#'all the data (model and obs) are excluded when computing the climatologies. +#' +#'@param var_exp Model data: c(nmod/nexp, nmemb/nparam, nsdates, nltime) up to +#' c(nmod/nexp, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon). +#'@param var_obs Observational data: c(nobs, nmemb, nsdates, nltime) up to +#' c(nobs, nmemb, nsdates, nltime, nlevel, nlat, nlon). +#'@param memb TRUE/FALSE (1 climatology for each member). Default = TRUE. +#'@param kharin TRUE/FALSE (if Kharin method is applied or not). +#' Default = FALSE. +#'@param NDV TRUE/FALSE (if Fuckar method is applied or not). Default = FALSE. +#' +#'@return +#'\item{clim_exp}{Array with same dimensions as var_exp except the third +#' (starting dates) and, depending on the parameters, the second (members), +#' which disappear.} +#'\item{clim_obs}{Array with same dimensions as var_obs except the third +#' (starting dates) and, depending on the parameters, the second (members), +#' which disappear.} +#'@keywords datagen +#'@author History:\cr +#' 0.9 - 2011-03 (V. Guemas, \email{virginie.guemas@@ic3.cat}) - Original code\cr +#' 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to R CRAN +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'PlotClim(clim$clim_exp, clim$clim_obs, +#' toptitle = paste('sea surface temperature climatologies'), +#' ytitle = 'K', monini = 11, listexp = c('CMIP5 IC3'), +#' listobs = c('ERSST'), biglab = FALSE, fileout = 'tos_clim.eps') +#'@export Clim <- function(var_exp, var_obs, memb = TRUE, kharin = FALSE, NDV = FALSE) { # # Enlarge the number of dimensions of var_exp and var_obs to 7 if necessary diff --git a/R/Cluster.R b/R/Cluster.R index b72b5e49967924b1908ebec60cf478850b6e1947..da9c62a67f0b0258f67d4a5a2f1eb5bea8ac67ad 100644 --- a/R/Cluster.R +++ b/R/Cluster.R @@ -1,3 +1,115 @@ +#'K-means Clustering +#' +#'This function computes cluster centers and their time series of occurrences, +#'with the K-means clustering method using Euclidean distance, of an array of +#'input data with any number of dimensions, one of them (the 'posdates'th) +#'corresponding to time. By default the first dimension is expected to +#'correspond to time. Specifically, it partitions the array along time axis in +#'K groups or clusters in which each space vector/array belongs to (i.e., is a +#'member of) the cluster with the nearest center or centroid. This function +#'relies on the NbClust package (Charrad et al., 2014 JSS). +#' +#'@param var An array with any number of dimensions, one of them (the +#' 'posdates'th) corresponding to time with either area-averages over a +#' series of domains or the grid points for any sptial grid structure (x), +#' (y), (z), (x,y), (x,y,z), (y,z), ... +#'@param weights A vector/array of multiplicative weights based on the areas +#' covering each domain/region or grid-cell of var; the dimensions of weights +#' vector must be equal to the dimensions of 'var' without the +#' 'posdates'th dimension. +#'@param nclusters This is positive integer K that must be bigger than 1. +#' K is the number of clusters to be computed, or K initial cluster centers +#' to be used in the method. Default is NULL and then user has to specify +#' which index from NbClust and the associated criteria for selecting the +#' optimal number of clusters will be used for K-means clustering of var. +#'@param index A validity index from NbClust package that can be used to +#' determine optimal K if K is not specified as positive integer bigger than +#' 1 or initial/seed cluster centers in nclusters. 'sdindex' is deafult +#' (Halkidi et al. 2001, JIIS). Other indices also available in NBClust are +#' "kl", "ch", "hartigan", "ccc", "scott", "marriot", "trcovw", "tracew", +#' "friedman", "rubin", "cindex", "db", "silhouette", "duda", "pseudot2", +#' "beale", "ratkowsky", "ball", "ptbiserial", "gap", "frey", "mcclain", +#' "gamma", "gplus", "tau", "dunn", "hubert", "sdindex", and "sdbw". +#' One can also use all of them with the option 'alllong' or almost all indices +#' except gap, gamma, gplus and tau with 'all', when the optimal number of +#' clusters K is detremined by the majority rule (the maximum of histogram of +#' the results of all indices with finite solutions). Use of some indices on +#' a big and/or unstructured dataset can be computationally intense and/or +#' could lead to numerical singularity. +#'@param posdates The index of the dimension that corresponds to time in the +#' provided array in the parameter 'var', the first by default. +#' +#'@return +#'\item{cluster}{ +#' A vector (time series) of integers indicating the occurrence +#' of a cluster, i.e., when 'certain data member in time is allocated to a +#' specific cluster (e.g., 2 1 3 1 1 1 ..). +#'} +#'\item{centers}{ +#' A matrix of cluster centres or centroids (e.g. +#' [1:K, 1:spatial degrees of freedom]). +#'} +#'\item{totss}{ +#' The total sum of squares. +#'} +#'\item{withinss}{ +#' A vector of within-cluster sum of squares, one component +#' per cluster. +#'} +#'\item{tot.withinss}{ +#' Total within-cluster sum of squares, +#' i.e., sum(withinss). +#'} +#'\item{betweenss}{ +#' The between-cluster sum of squares, i.e. totss-tot.withinss. +#'} +#'\item{size}{ +#'The number of points in each cluster. +#'} +#' +#'@references +#'Wilks, 2011, Statistical Methods in the Atmospheric Sciences, 3rd ed., Elsevire, pp 676. +#'@keywords datagen +#'@author History:\cr +#' 1.0 # 2014-10 (N.S. Fuckar, \email{neven.fuckar@@bsc.es}) - Original code +#'@examples +#'# Generating synthetic data +#'a1 <- array(dim = c(200, 4)) +#'mean1 <- 0 +#'sd1 <- 0.3 +#' +#'c0 <- seq(1, 200) +#'c1 <- sort(sample(x = 1:200, size = sample(x = 50:150, size = 1), replace = FALSE)) +#'x1 <- c(1, 1, 1, 1) +#'for (i1 in c1) { +#' a1[i1, ] <- x1 + rnorm(4, mean = mean1, sd = sd1) +#'} +#' +#'c1p5 <- c0[!(c0 \%in\% c1)] +#'c2 <- c1p5[seq(1, length(c1p5), 2)] +#'x2 <- c(2, 2, 4, 4) +#'for (i2 in c2) { +#' a1[i2, ] <- x2 + rnorm(4, mean = mean1, sd = sd1) +#'} +#' +#'c3 <- c1p5[seq(2, length(c1p5), 2)] +#'x3 <- c(3, 3, 1, 1) +#'for (i3 in c3) { +#' a1[i3, ] <- x3 + rnorm(4, mean = mean1, sd = sd1) +#'} +#' +#'# Computing the clusters +#'res1 <- Cluster(var = a1, weights = array(1, dim = dim(a1)[2]), nclusters = 3) +#'print(res1$cluster) +#'print(res1$centers) +#' +#'res2 <- Cluster(var = a1, weights = array(1, dim = dim(a1)[2])) +#'print(res2$cluster) +#'print(res2$centers) +#'@import NbClust +#'@importFrom stats kmeans +#'@importFrom grDevices pdf dev.off +#'@export Cluster <- function(var, weights, nclusters = NULL, index = 'sdindex', posdates = 1) { # Check var diff --git a/R/ColorBar.R b/R/ColorBar.R index d47c3103a25f16c8054d649e72c74b0c6109fc24..b475d08ad93b881363a141b5384c818da5f4740f 100644 --- a/R/ColorBar.R +++ b/R/ColorBar.R @@ -1,3 +1,154 @@ +#'Draws a Color Bar +#' +#'Generates a color bar to use as colouring function for map plots and +#'optionally draws it (horizontally or vertically) to be added to map +#'multipanels or plots. It is possible to draw triangles at the ends of the +#'colour bar to represent values that go beyond the range of interest. A +#'number of options is provided to adjust the colours and the position and +#'size of the components. The drawn colour bar spans a whole figure region +#'and is compatible with figure layouts.\cr\cr +#'The generated colour bar consists of a set of breaks that define the +#'length(brks) - 1 intervals to classify each of the values in each of the +#'grid cells of a two-dimensional field. The corresponding grid cell of a +#'given value of the field will be coloured in function of the interval it +#'belongs to.\cr\cr +#'The only mandatory parameters are 'var_limits' or 'brks' (in its second +#'format, see below). +#' +#'@param brks Can be provided in two formats: +#'\itemize{ +#' \item{A single value with the number of breaks to be generated +#' automatically, between the minimum and maximum specified in 'var_limits' +#' (both inclusive). Hence the parameter 'var_limits' is mandatory if 'brks' +#' is provided with this format. If 'bar_limits' is additionally provided, +#' values only between 'bar_limits' will be generated. The higher the value +#' of 'brks', the smoother the plot will look.} +#' \item{A vector with the actual values of the desired breaks. Values will +#' be reordered by force to ascending order. If provided in this format, no +#' other parameters are required to generate/plot the colour bar.} +#'} +#' This parameter is optional if 'var_limits' is specified. If 'brks' not +#' specified but 'cols' is specified, it will take as value length(cols) + 1. +#' If 'cols' is not specified either, 'brks' will take 21 as value. +#'@param cols Vector of length(brks) - 1 valid colour identifiers, for each +#' interval defined by the breaks. This parameter is optional and will be +#' filled in with a vector of length(brks) - 1 colours generated with the +#' function provided in 'color_fun' (\code{clim.colors} by default).\cr 'cols' +#' can have one additional colour at the beginning and/or at the end with the +#' aim to colour field values beyond the range of interest represented in the +#' colour bar. If any of these extra colours is provided, parameter +#' 'triangle_ends' becomes mandatory in order to disambiguate which of the +#' ends the colours have been provided for. +#'@param vertical TRUE/FALSE for vertical/horizontal colour bar +#' (disregarded if plot = FALSE). +#'@param subsampleg The first of each subsampleg breaks will be ticked on the +#' colorbar. Takes by default an approximation of a value that yields a +#' readable tick arrangement (extreme breaks always ticked). If set to 0 or +#' lower, no labels are drawn. See the code of the function for details or +#' use 'extra_labels' for customized tick arrangements. +#'@param bar_limits Vector of two numeric values with the extremes of the +#' range of values represented in the colour bar. If 'var_limits' go beyond +#' this interval, the drawing of triangle extremes is triggered at the +#' corresponding sides, painted in 'col_inf' and 'col_sup'. Either of them +#' can be set as NA and will then take as value the corresponding extreme in +#' 'var_limits' (hence a triangle end won't be triggered for these sides). +#' Takes as default the extremes of 'brks' if available, else the same values +#' as 'var_limits'. +#'@param var_limits Vector of two numeric values with the minimum and maximum +#' values of the field to represent. These are used to know whether to draw +#' triangle ends at the extremes of the colour bar and what colour to fill +#' them in with. If not specified, take the same value as the extremes of +#' 'brks'. Hence the parameter 'brks' is mandatory if 'var_limits' is not +#' specified. +#'@param triangle_ends Vector of two logical elements, indicating whether to +#' force the drawing of triangle ends at each of the extremes of the colour +#' bar. This choice is automatically made from the provided 'brks', +#' 'bar_limits', 'var_limits', 'col_inf' and 'col_sup', but the behaviour +#' can be manually forced to draw or not to draw the triangle ends with this +#' parameter. If 'cols' is provided, 'col_inf' and 'col_sup' will take +#' priority over 'triangle_ends' when deciding whether to draw the triangle +#' ends or not. +#'@param col_inf Colour to fill the inferior triangle end with. Useful if +#' specifying colours manually with parameter 'cols', to specify the colour +#' and to trigger the drawing of the lower extreme triangle, or if 'cols' is +#' not specified, to replace the colour automatically generated by ColorBar(). +#'@param col_sup Colour to fill the superior triangle end with. Useful if +#' specifying colours manually with parameter 'cols', to specify the colour +#' and to trigger the drawing of the upper extreme triangle, or if 'cols' is +#' not specified, to replace the colour automatically generated by ColorBar(). +#'@param color_fun Function to generate the colours of the color bar. Must +#' take an integer and must return as many colours. The returned colour vector +#' can have the attribute 'na_color', with a colour to draw NA values. This +#' parameter is set by default to clim.palette(). +#'@param plot Logical value indicating whether to only compute its breaks and +#' colours (FALSE) or to also draw it on the current device (TRUE). +#'@param draw_ticks Whether to draw ticks for the labels along the colour bar +#' (TRUE) or not (FALSE). TRUE by default. Disregarded if 'plot = FALSE'. +#'@param draw_separators Whether to draw black lines in the borders of each of +#' the colour rectancles of the colour bar (TRUE) or not (FALSE). FALSE by +#' default. Disregarded if 'plot = FALSE'. +#'@param triangle_ends_scale Scale factor for the drawn triangle ends of the +#' colour bar, if drawn at all. Takes 1 by default (rectangle triangle +#' proportional to the thickness of the colour bar). Disregarded if +#' 'plot = FALSE'. +#'@param extra_labels Numeric vector of extra labels to draw along axis of +#' the colour bar. The number of provided decimals will be conserved. +#' Disregarded if 'plot = FALSE'. +#'@param title Title to draw on top of the colour bar, most commonly with the +#' units of the represented field in the neighbour figures. Empty by default. +#'@param title_scale Scale factor for the 'title' of the colour bar. +#' Takes 1 by default. +#'@param label_scale Scale factor for the labels of the colour bar. +#' Takes 1 by default. +#'@param tick_scale Scale factor for the length of the ticks of the labels +#' along the colour bar. Takes 1 by default. +#'@param extra_margin Extra margins to be added around the colour bar, +#' in the format c(y1, x1, y2, x2). The units are margin lines. Takes +#' rep(0, 4) by default. +#'@param label_digits Number of significant digits to be displayed in the +#' labels of the colour bar, usually to avoid too many decimal digits +#' overflowing the figure region. This does not have effect over the labels +#' provided in 'extra_labels'. Takes 4 by default. +#'@param ... Arguments to be passed to the method. Only accepts the following +#' graphical parameters:\cr adj ann ask bg bty cex.lab cex.main cex.sub cin +#' col.axis col.lab col.main col.sub cra crt csi cxy err family fg fig fin +#' font font.axis font.lab font.main font.sub lend lheight ljoin lmitre lty +#' lwd mai mex mfcol mfrow mfg mkh oma omd omi page pch pin plt pty smo srt +#' tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog.\cr For more +#' information about the parameters see `par`. +#' +#'@return +#'\item{brks}{ +#' Breaks used for splitting the range in intervals. +#'} +#'\item{cols}{ +#' Colours generated for each of the length(brks) - 1 intervals. +#' Always of length length(brks) - 1. +#'} +#'\item{col_inf}{ +#' Colour used to draw the lower triangle end in the colour +#' bar (NULL if not drawn at all). +#'} +#'\item{col_sup}{ +#' Colour used to draw the upper triangle end in the colour +#' bar (NULL if not drawn at all). +#'} +#' +#'@keywords dplot +#'@author History:\cr +#' 0.1 - 2012-04 (V. Guemas, \email{virginie.guemas@@bsc.es}) - Original code\cr +#' 0.2 - 2013-04 (I. Andreu-Burillo, \email{isabel.andreu-burillo@@bsc.es}) - Vert option\cr +#' 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@bsc.es}) - Formatting to CRAN\cr +#' 1.1 - 2013-09 (C. Prodhomme, \email{chloe.prodhomme@@bsc.es}) - Add cex option\cr +#' 1.2 - 2016-08 (N. Manubens, \email{nicolau.manubens@@bsc.es}) - New ColorBar\cr +#' (V. Torralba, \email{veronica.torralba@@bsc.es}) +#'@examples +#'cols <- c("dodgerblue4", "dodgerblue1", "forestgreen", "yellowgreen", "white", +#' "white", "yellow", "orange", "red", "saddlebrown") +#'lims <- seq(-1, 1, 0.2) +#'ColorBar(lims, cols) +#'@importFrom grDevices col2rgb rgb +#'@export ColorBar <- function(brks = NULL, cols = NULL, vertical = TRUE, subsampleg = NULL, bar_limits = NULL, var_limits = NULL, triangle_ends = NULL, col_inf = NULL, col_sup = NULL, diff --git a/R/Composite.R b/R/Composite.R index c8294fd26c77ec2cdf7421d990b3e25f892a7cf9..865501d6c91a3e5d672093471cbdbbdff606e080 100644 --- a/R/Composite.R +++ b/R/Composite.R @@ -1,7 +1,78 @@ +#'Computes composites +#' +#'Composites a 3-d field var(x, y, time) according to the indices of +#'mode/cluster occurrences in time and computes the pvalues (t-test). x and y +#'are typically lon and lat, but function can accept other 2-d fields such as +#'lat and depth, lon and depth, etc. +#' +#'@param var 3-dimensional array (x, y, time) containing the variable to +#' composite. +#'@param occ 1-dimensional array for the occurrence time series of +#' mode(s)/cluster(s). +#' (*1) When one wants to composite all modes, e.g., all K = 3 clusters then +#' for example occurrences could look like: 1 1 2 3 2 3 1 3 3 2 3 2 2 3 2. +#' (*2) Otherwise for compositing only the 2nd mode or cluster of the above +#' example occurrences should look like 0 0 1 0 1 0 0 0 0 1 0 1 1 0 1. +#'@param lag Lag time step (an integer), e.g., for lag = 2 composite will +#' use +2 occurrences (i.e., shifted 2 time steps forward). Default is lag = 0. +#'@param eno For using the effective sample size (TRUE) or the total sample +#' size (FALSE that is the default) for the number of degrees of freedom. +#'@param fileout Name of the .sav output file (NULL is the default). +#' +#'@return +#'\item{$composite}{ +#' 3-d array (x, y, k) containing the composites k=1,..,K for case (*1) +#' or only k=1 for any specific cluster, i.e., case (*2). +#'} +#'\item{$pvalue}{ +#' 3-d array (x, y, k) containing the pvalue of the +#' composites obtained through a t-test that accounts for the serial +#' dependence of the data with the same structure as Composite. +#'} +#'@keywords datagen +#'@author History: +#' 0.1 # 2014-08 (N.S. Fuckar, \email{neven.fuckar@@bsc.es}) # Original code +#' +#'@examples +#'blank <- array(0, dim=c(20, 10, 30)) +#' +#'x1 <- blank +#'t1 <- blank +#'f1 <- blank +#' +#'for (i in 1:20) { +#' x1[i,,] <- i +#'} +#' +#'for (i in 1:30) { +#' t1[,,i] <- i +#'} +#' +#'# This is 2D propagating sin wave example, where we use (x,y,t) structure of +#'# f1 wave field. Compositing (like using stroboscopicc light) at different time +#'# steps can lead to modification or cancelation of wave pattern. +#' +#'for (i in 1:20) { +#' for (j in 1:30) { +#' f1[i,,j] <- 3*sin(2*pi*x1[i,,j]/5. - 2*pi*t1[i,,j]/6.) +#' } +#'} +#' +#'occ1 <- rep(0, 30) +#'occ1[c(2, 5, 8, 11, 14, 17, 20, 23)] <- 1 +#' +#'filled.contour(Composite(var=f1, occ=occ1)$composite[,,1]) +#' +#'occ2 <- rep(0, 30) +#'occ2[c(3, 9, 15, 21)] <- 1 +#' +#'filled.contour(Composite(var=f1, occ=occ2)$composite[,,1]) +#'@importFrom stats sd pt +#'@export Composite <- function(var, occ, lag = 0, eno = FALSE, fileout = NULL) { if ( dim(var)[3] != length(occ) ) { - stop("temporal dimension of var is not equal to length of occ.") + stop("Temporal dimension of var is not equal to length of occ.") } K <- max(occ) composite <- array(dim = c(dim(var)[1:2], K)) diff --git a/R/ConfigAddEntry.R b/R/ConfigAddEntry.R deleted file mode 100644 index a8d2fa54a7ee32e7246f184d5bcf469dccfdc34b..0000000000000000000000000000000000000000 --- a/R/ConfigAddEntry.R +++ /dev/null @@ -1,42 +0,0 @@ -ConfigAddEntry <- function(configuration, dataset_type, position = 'last', dataset_name = ".*", var_name = ".*", main_path = "*", file_path = "*", nc_var_name = "*", suffix = "*", varmin = "*", varmax = "*") { - table_name <- dataset_type - if (dataset_name == ".*") { - if (var_name == ".*") { - level <- 1 - } else { - level <- 3 - } - } else { - if (var_name == ".*") { - level <- 2 - } else { - level <- 4 - } - } - - index_of_first <- 0 - index_of_last <- 0 - for (i in 1:level) { - index_of_first <- index_of_first + ifelse(i == 1, 1, length(configuration[[table_name]][[i - 1]])) - index_of_last <- index_of_last + length(configuration[[table_name]][[i]]) - } - - if (position == 'last') { - position <- index_of_last - index_of_first + 1 + 1 - } else if (position == 'first') { - position <- 1 - } else { - if (position < index_of_first || position > index_of_last + 1) { - stop("'position' must be in the range [index of first table entry in corresponding level, index of last table entry in corresponding level + 1]") - } - position <- position - index_of_first + 1 - } - - if (dataset_type == 'experiments' || dataset_type == 'observations') { - configuration[[table_name]][[level]] <- append(configuration[[table_name]][[level]], list(c(dataset_name, var_name, main_path, file_path, nc_var_name, suffix, varmin, varmax)), after = position - 1) - } else { - stop("'dataset_type' must be one of 'experiments' or 'observations'") - } - - configuration -} diff --git a/R/ConfigApplyMatchingEntries.R b/R/ConfigApplyMatchingEntries.R index 4f2c01095ebf72fb10e10f7a6d2ef99d92463868..5a5c8cfa2048c703d361d5e624251919cecb22d2 100644 --- a/R/ConfigApplyMatchingEntries.R +++ b/R/ConfigApplyMatchingEntries.R @@ -1,3 +1,59 @@ +#'Apply Matching Entries To Dataset Name And Variable Name To Find Related Info +#' +#'Given a pair of dataset name and variable name, this function determines +#'applies all the matching entries found in the corresponding configuration +#'table to work out the dataset main path, file path, actual name of variable +#'inside NetCDF files, ... +#' +#'@param configuration Configuration object obtained from ConfigFileOpen() +#' or ConfigFileCreate(). +#'@param var Name of the variable to load. Will be interpreted as a string, +#' regular expressions do not apply here. +#' Examples: 'tas' or 'tasmax_q90'. +#'@param exp Set of experimental dataset identifiers. Will be interpreted as +#' a strings, regular expressions do not apply here. Can be NULL (not to +#' check in experimental dataset tables), and takes by default NULL. +#' Examples: c('EnsEcmwfSeas', 'EnsUkmoSeas'), c('i00k'). +#'@param obs Set of observational dataset identifiers. Will be interpreted as +#' a strings, regular expressions do not apply here. Can be NULL (not to +#' check in observational dataset tables), and takes by default NULL. +#' Examples: c('GLORYS', 'ERAint'), c('NCEP'). +#'@param show_entries Flag to stipulate whether to show the found matching +#' entries for all datasets and variable name. +#'@param show_result Flag to stipulate whether to show the result of applying +#' all the matching entries (dataset main path, file path, ...). +#' +#'@return A list with the information resulting of applying the matching +#' entries is returned. +#'@seealso ConfigApplyMatchingEntries, ConfigEditDefinition, +#' ConfigEditEntry, ConfigFileOpen, ConfigShowSimilarEntries, +#' ConfigShowTable +#'@keywords datagen +#'@author History:\cr +#' 0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - First version\cr +#' 1.0 - 2015-11 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Removed grid column and storage types +#'@examples +#'# Create an empty configuration file +#'config_file <- paste0(tempdir(), "/example.conf") +#'s2dverification:::ConfigFileCreate(config_file, confirm = FALSE) +#'# Open it into a configuration object +#'configuration <- ConfigFileOpen(config_file) +#'# Add an entry at the bottom of 4th level of file-per-startdate experiments +#'# table which will associate the experiment "ExampleExperiment2" and variable +#'# "ExampleVariable" to some information about its location. +#'configuration <- ConfigAddEntry(configuration, "experiments", +#' "last", "ExampleExperiment2", "ExampleVariable", +#' "/path/to/ExampleExperiment2/", +#' "ExampleVariable/ExampleVariable_$START_DATE$.nc") +#'# Edit entry to generalize for any variable. Changing variable needs . +#'configuration <- ConfigEditEntry(configuration, "experiments", 1, +#' var_name = ".*", +#' file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") +#'# Now apply matching entries for variable and experiment name and show the +#'# result +#'match_info <- ConfigApplyMatchingEntries(configuration, 'tas', +#' exp = c('ExampleExperiment2'), show_result = TRUE) +#'@export ConfigApplyMatchingEntries <- function(configuration, var, exp = NULL, obs = NULL, show_entries = FALSE, show_result = TRUE) { ## Function to tell if a regexpr() match is a complete match to a specified name isFullMatch <- function(x, name) { diff --git a/R/ConfigEditDefinition.R b/R/ConfigEditDefinition.R index eefb56628bd97227830ba7121f5602deec1dcfb8..63f73971fd5f0704c29707cc13304be1215df2e1 100644 --- a/R/ConfigEditDefinition.R +++ b/R/ConfigEditDefinition.R @@ -1,3 +1,48 @@ +#'Add Modify Or Remove Variable Definitions In Configuration +#' +#'These functions help in adding, modifying or removing variable definitions +#'in a configuration object obtained with \code{\link{ConfigFileOpen}} or +#'\code{\link{ConfigFileCreate}}. ConfigEditDefinition() will add the +#'definition if not existing. +#' +#'@param configuration Configuration object obtained wit ConfigFileOpen() or +#' ConfigFileCreate(). +#'@param name Name of the variable to add/modify/remove. +#'@param value Value to associate to the variable. +#'@param confirm Flag to stipulate whether to ask for confirmation if the +#' variable is being modified. Takes by default TRUE. +#' +#'@return A modified configuration object is returned. +#'@seealso [ConfigApplyMatchingEntries()], [ConfigEditDefinition()], +#' [ConfigEditEntry()], [ConfigFileOpen()], [ConfigShowSimilarEntries()], +#' [ConfigShowTable()]. +#'@author History: +#' 0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - First version +#'@keywords datagen +#'@examples +#'# Create an empty configuration file +#'config_file <- paste0(tempdir(), "/example.conf") +#'ConfigFileCreate(config_file, confirm = FALSE) +#'# Open it into a configuration object +#'configuration <- ConfigFileOpen(config_file) +#'# Add an entry at the bottom of 4th level of file-per-startdate experiments +#'# table which will associate the experiment "ExampleExperiment2" and variable +#'# "ExampleVariable" to some information about its location. +#'configuration <- ConfigAddEntry(configuration, "experiments", +#' "last", "ExampleExperiment2", "ExampleVariable", +#' "/path/to/ExampleExperiment2/", +#' "ExampleVariable/ExampleVariable_$START_DATE$.nc") +#'# Edit entry to generalize for any variable. Changing variable needs . +#'configuration <- ConfigEditEntry(configuration, "experiments", 1, +#' var_name = ".*", +#' file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") +#'# Now apply matching entries for variable and experiment name and show the +#'# result +#'match_info <- ConfigApplyMatchingEntries(configuration, 'tas', +#' exp = c('ExampleExperiment2'), show_result = TRUE) +#' +#'@rdname ConfigEditDefinition +#'@export ConfigEditDefinition <- function(configuration, name, value, confirm = TRUE) { continue <- TRUE if (name %in% names(configuration$definitions)) { @@ -14,3 +59,10 @@ ConfigEditDefinition <- function(configuration, name, value, confirm = TRUE) { configuration } +#'@rdname ConfigEditDefinition +#'@export +ConfigRemoveDefinition <- function(configuration, name) { + configuration$definitions[[name]] <- NULL + + configuration +} diff --git a/R/ConfigEditEntry.R b/R/ConfigEditEntry.R index 40fe55d2402a54df60dfe8c6b1aa3bf859bf0b22..619af304d9ff949f44772b2d30edbb57e0662453 100644 --- a/R/ConfigEditEntry.R +++ b/R/ConfigEditEntry.R @@ -1,3 +1,84 @@ +#'Add, Remove Or Edit Entries In The Configuration +#' +#'ConfigAddEntry(), ConfigEditEntry() and ConfigRemoveEntry() are functions +#'to manage entries in a configuration object created with ConfigFileOpen().\cr +#'Before adding an entry, make sure the defaults don't do already what you +#'want (ConfigShowDefinitions(), ConfigShowTable()).\cr +#'Before adding an entry, make sure it doesn't override and spoil what other +#'entries do (ConfigShowTable(), ConfigFileOpen()).\cr +#'Before adding an entry, make sure there aren't other entries that already +#'do what you want (ConfigShowSimilarEntries()). +#' +#'@param configuration Configuration object obtained via ConfigFileOpen() +#' or ConfigFileCreate() that will be modified accordingly. +#'@param dataset_type Whether to modify a table of experimental datasets or +#' a table of observational datasets. Can take values 'experiments' or +#' 'observations' respectively. +#'@param position 'position' tells the index in the table of the entry to +#' edit or remove. Use ConfigShowTable() to see the index of the entry. +#' In ConfigAddEntry() it can also take the value "last" (default), that will +#' put the entry at the end of the corresponding level, or "first" at the +#' beginning. See ?ConfigFileOpen for more information. +#' If 'dataset_name' and 'var_name' are specified this argument is ignored in +#' ConfigRemoveEntry(). +#'@param dataset_name,var_name,main_path,file_path,nc_var_name,suffix,varmin,varmax +#' These parameters tell the dataset name, variable name, main path, ..., of +#' the entry to add, edit or remove.\cr 'dataset_name' and 'var_name' can take +#' as a value a POSIX 1003.2 regular expression (see ?ConfigFileOpen).\cr +#' Other parameters can take as a value a shell globbing expression +#' (see ?ConfigFileOpen).\cr +#' 'dataset_name' and 'var_name' take by default the regular expression '.*' +#' (match any dataset and variable name), and the others take by default '*' +#' (associate to the pair 'dataset_name' and 'var_name' all the defined +#' default values. In this case '*' has a special behaviour, it won't be +#' used as a shell globbing expression. See ?ConfigFileOpen and +#' ?ConfigShowDefinitions).\cr +#' 'var_min' and 'var_max' must be a character string.\cr +#' To define these values, you can use defined variables via $VARIABLE_NAME$ +#' or other entry attributes via $ATTRIBUTE_NAME$. See ?ConfigFileOpen for +#' more information. +#' +#'@return The function returns an accordingly modified configuration object. +#' To apply the changes in the configuration file it must be saved using +#' ConfigFileSave(). +#' +#'@seealso ConfigApplyMatchingEntries, ConfigEditDefinition, ConfigEditEntry, +#' ConfigFileOpen, ConfigShowSimilarEntries, ConfigShowTable +#'@keywords datagen +#'@author History:\cr +#' 0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - First version\cr +#' 1.0 - 2015-11 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Removed grid column and storage formats +#'@examples +#'# Create an empty configuration file +#'config_file <- paste0(tempdir(), "/example.conf") +#'ConfigFileCreate(config_file, confirm = FALSE) +#'# Open it into a configuration object +#'configuration <- ConfigFileOpen(config_file) +#'# Add an entry at the bottom of 4th level of file-per-startdate experiments +#'# table which will associate the experiment "ExampleExperiment" and variable +#'# "ExampleVariable" to some information about its location. +#'configuration <- ConfigAddEntry(configuration, "experiments", +#' "last", "ExampleExperiment", "ExampleVariable", +#' "/path/to/ExampleExperiment/", +#' "ExampleVariable/ExampleVariable_$START_DATE$.nc") +#'# Add another entry +#'configuration <- ConfigAddEntry(configuration, "experiments", +#' "last", "ExampleExperiment2", "ExampleVariable", +#' "/path/to/ExampleExperiment2/", +#' "ExampleVariable/ExampleVariable_$START_DATE$.nc") +#'# Edit second entry to generalize for any variable. Changing variable needs . +#'configuration <- ConfigEditEntry(configuration, "experiments", 2, +#' var_name = ".*", +#' file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") +#'# Remove first entry +#'configuration <- ConfigRemoveEntry(configuration, "experiments", +#' "ExampleExperiment", "ExampleVariable") +#'# Show results +#'ConfigShowTable(configuration, "experiments") +#'# Save the configuration +#'ConfigFileSave(configuration, config_file, confirm = FALSE) +#'@rdname ConfigEditEntry +#'@export ConfigEditEntry <- function(configuration, dataset_type, position, dataset_name = NULL, var_name = NULL, main_path = NULL, file_path = NULL, nc_var_name = NULL, suffix = NULL, varmin = NULL, varmax = NULL) { if (!(dataset_type %in% c('experiments', 'observations'))) { stop("Error: 'dataset_type' must be one of 'experiments' or 'observations'") @@ -28,3 +109,100 @@ ConfigEditEntry <- function(configuration, dataset_type, position, dataset_name configuration } +#'@rdname ConfigEditEntry +#'@export +ConfigAddEntry <- function(configuration, dataset_type, position = 'last', dataset_name = ".*", var_name = ".*", main_path = "*", file_path = "*", nc_var_name = "*", suffix = "*", varmin = "*", varmax = "*") { + table_name <- dataset_type + if (dataset_name == ".*") { + if (var_name == ".*") { + level <- 1 + } else { + level <- 3 + } + } else { + if (var_name == ".*") { + level <- 2 + } else { + level <- 4 + } + } + + index_of_first <- 0 + index_of_last <- 0 + for (i in 1:level) { + index_of_first <- index_of_first + ifelse(i == 1, 1, length(configuration[[table_name]][[i - 1]])) + index_of_last <- index_of_last + length(configuration[[table_name]][[i]]) + } + + if (position == 'last') { + position <- index_of_last - index_of_first + 1 + 1 + } else if (position == 'first') { + position <- 1 + } else { + if (position < index_of_first || position > index_of_last + 1) { + stop("'position' must be in the range [index of first table entry in corresponding level, index of last table entry in corresponding level + 1]") + } + position <- position - index_of_first + 1 + } + + if (dataset_type == 'experiments' || dataset_type == 'observations') { + configuration[[table_name]][[level]] <- append(configuration[[table_name]][[level]], list(c(dataset_name, var_name, main_path, file_path, nc_var_name, suffix, varmin, varmax)), after = position - 1) + } else { + stop("'dataset_type' must be one of 'experiments' or 'observations'") + } + + configuration +} +#'@rdname ConfigEditEntry +#'@export +ConfigRemoveEntry <- function(configuration, dataset_type, dataset_name = NULL, var_name = NULL, position = NULL) { + table_name <- dataset_type + if (!is.null(dataset_name) && !is.null(var_name)) { + if (dataset_name == ".*") { + if (var_name == ".*") { + level <- 1 + } else { + level <- 3 + } + } else { + if (var_name == ".*") { + level <- 2 + } else { + level <- 4 + } + } + + position <- which(unlist(lapply(configuration[[table_name]][[level]], "[", 1)) == dataset_name & + unlist(lapply(configuration[[table_name]][[level]], "[", 2)) == var_name)[1] + if (is.na(position)) { + stop("No entry found that matches 'dataset_name' and 'var_name'.") + } + } else { + if (is.null(position)) { + stop("At least ('dataset_name', 'var_name') or 'position' must be specified.") + } + + all_entries <- length(unlist(configuration[[table_name]], recursive = FALSE)) + if (position < 1 || position > all_entries) { + stop("'position' must be in the range [1, # of table entries]") + } + + found <- FALSE + level <- 1 + index_of_first <- 1 + while (!found && level < 5) { + if (position <= (index_of_first + length(configuration[[table_name]][[level]]) - 1)) { + found <- TRUE + } else { + index_of_first <- index_of_first + length(configuration[[table_name]][[level]]) + level <- level + 1 + } + } + position <- position - index_of_first + 1 + } + + configuration[[table_name]][[level]][[position]] <- NULL + + configuration +} + diff --git a/R/ConfigFileCreate.R b/R/ConfigFileCreate.R deleted file mode 100644 index 98db52ff89c0727536d001c9f4668360af9d0eea..0000000000000000000000000000000000000000 --- a/R/ConfigFileCreate.R +++ /dev/null @@ -1,14 +0,0 @@ -ConfigFileCreate <- function(file_path, confirm = TRUE) { - success <- ConfigFileSave(list(definitions = list( - DEFAULT_EXP_MAIN_PATH = "$EXP_NAME$", - DEFAULT_EXP_FILE_PATH = "$STORE_FREQ$/$VAR_NAME$_$START_DATE$.nc", - DEFAULT_NC_VAR_NAME = "$VAR_NAME$", - DEFAULT_SUFFIX = "", DEFAULT_VAR_MIN = "", - DEFAULT_VAR_MAX = "", DEFAULT_OBS_MAIN_PATH = "$OBS_NAME$", - DEFAULT_OBS_FILE_PATH = "$STORE_FREQ$/$VAR_NAME$_$YEAR$$MONTH$.nc", - DEFAULT_DIM_NAME_LONGITUDES = "longitude", DEFAULT_DIM_NAME_LATITUDES = "latitude", - DEFAULT_DIM_NAME_MEMBERS = "ensemble")), file_path, confirm = confirm) - if (success) { - .warning("You have just created an empty configuration file. You can edit it with ConfigAddEntry(). You can edit the defaults according to your needs with the functions ConfigFileOpen(), ConfigEditDefinition() and ConfigFileSave() or edit the file manually as specified in ?ConfigFileOpen.") - } -} diff --git a/R/ConfigFileOpen.R b/R/ConfigFileOpen.R index b4d2bc1a077b1aac62147580fca6ca102e3e3bb8..182b205e31f898fbec7ab32b4a6e9c699de14849 100644 --- a/R/ConfigFileOpen.R +++ b/R/ConfigFileOpen.R @@ -1,3 +1,183 @@ +#'Functions To Create Open And Save Configuration File +#' +#'These functions help in creating, opening and saving configuration files. +#' +#'@param file_path Path to the configuration file to create/open/save. +#'@param silent Flag to activate or deactivate verbose mode. +#' Defaults to FALSE (verbose mode on). +#'@param configuration Configuration object to save in a file. +#'@param confirm Flag to stipulate whether to ask for confirmation when +#' saving a configuration file that already exists.\cr +#' Defaults to TRUE (confirmation asked). +#'@param stop TRUE/FALSE whether to raise an error if not all the mandatory +#' default variables are defined in the configuration file. +#' +#'@details +#'ConfigFileOpen() loads all the data contained in the configuration file +#'specified as parameter 'file_path'. +#'Returns a configuration object with the variables needed for the +#'configuration file mechanism to work. +#'This function is called from inside the Load() function to load the +#'configuration file specified in 'configfile'.\cr\cr +#'ConfigFileCreate() creates an empty configuration file and saves it to +#'the specified path. It may be opened later with ConfigFileOpen() to be edited. +#' Some default values are set when creating a file with this function, you +#'can check these with ConfigShowDefinitions().\cr\cr +#'ConfigFileSave() saves a configuration object into a file, which may then +#'be used from Load().\cr\cr +#'Two examples of configuration files can be found inside the 'inst/config/' +#'folder in the package: +#' \itemize{ +#' \item{BSC.conf: configuration file used at BSC-CNS. Contains location +#' data on several datasets and variables.} +#' \item{template.conf: very simple configuration file intended to be used as +#' pattern when starting from scratch.} +#' } +#'How the configuration file works:\cr +#'~~~~~~~~~~~~~~~~~~~~~~~~~~~~\cr +#'It contains one list and two tables.\cr +#'Each of these have a header that starts with '!!'. These are key lines and +#'should not be removed or reordered.\cr +#'Lines starting with '#' and blank lines will be ignored. +#'The list should contains variable definitions and default value definitions.\cr +#'The first table contains information about experiments.\cr +#'The third table contains information about observations.\cr +#'Each table entry is a list of comma-separated elements.\cr +#'The two first are part of a key that is associated to a value formed by the +#'other elements.\cr +#'The key elements are a dataset identifier and a variable name.\cr +#'The value elements are the dataset main path, dataset file path, the +#'variable name inside the .nc file, a default suffix (explained below) and a +#'minimum and maximum vaues beyond which loaded data is deactivated.\cr +#'Given a dataset name and a variable name, a full path is obtained +#'concatenating the main path and the file path.\cr +#'Also the nc variable name, the suffixes and the limit values are obtained.\cr +#'Any of the elements in the keys can contain regular expressions[1] that will +#'cause matching for sets of dataset names or variable names.\cr +#'The dataset path and file path can contain shell globbing expressions[2] +#'that will cause matching for sets of paths when fetching the file in the +#'full path.\cr +#'The full path can point to an OPeNDAP URL.\cr +#'Any of the elements in the value can contain variables that will be replaced +#'to an associated string.\cr +#'Variables can be defined only in the list at the top of the file. \cr +#'The pattern of a variable definition is\cr +#'VARIABLE_NAME = VARIABLE_VALUE\cr +#'and can be accessed from within the table values or from within the variable +#'values as\cr +#' $VARIABLE_NAME$\cr +#'For example:\cr +#' FILE_NAME = tos.nc\cr +#' !!table of experiments\cr +#' ecmwf, tos, /path/to/dataset/, $FILE_NAME$\cr +#'There are some reserved variables that will offer information about the +#'store frequency, the current startdate Load() is fetching, etc:\cr +#' $VAR_NAME$, $START_DATE$, $STORE_FREQ$, $MEMBER_NUMBER$\cr +#' for experiments only: $EXP_NAME$\cr +#' for observations only: $OBS_NAME$, $YEAR$, $MONTH$, $DAY$\cr +#'Additionally, from an element in an entry value you can access the other +#'elements of the entry as:\cr +#' $EXP_MAIN_PATH$, $EXP_FILE_PATH$, \cr$VAR_NAME$, $SUFFIX$, $VAR_MIN$, $VAR_MAX$\cr +#'\cr +#'The variable $SUFFIX$ is useful because it can be used to take part in the +#'main or file path. For example: '/path/to$SUFFIX$/dataset/'.\cr +#'It will be replaced by the value in the column that corresponds to the +#'suffix unless the user specifies a different suffix via the parameter +#''suffixexp' or 'suffixobs'.\cr +#'This way the user is able to load two variables with the same name in the +#'same dataset but with slight modifications, with a suffix anywhere in the +#'path to the data that advices of this slight modification.\cr\cr +#'The entries in a table will be grouped in 4 levels of specificity: +#' \enumerate{ +#' \item{ +#'General entries:\cr +#' - the key dataset name and variable name are both a regular expression +#'matching any sequence of characters (.*) that will cause matching for any +#'pair of dataset and variable names\cr +#' Example: .*, .*, /dataset/main/path/, file/path, nc_var_name, suffix, +#'var_min, var_max +#' } +#' \item{ +#'Dataset entries:\cr +#' - the key variable name matches any sequence of characters\cr +#' Example: ecmwf, .*, /dataset/main/path/, file/path, nc_var_name, +#' suffix, var_min, var_max +#' } +#' \item{ +#'Variable entries:\cr +#' - the key dataset name matches any sequence of characters\cr +#' Example: .*, tos, /dataset/main/path/, file/path, nc_var_name, +#' suffix, var_min, var_max +#' } +#' \item{ +#' Specific entries:\cr +#' - both key values are specified\cr +#' Example: ecmwf, tos, /dataset/main/path/, file/path, nc_var_name, +#' suffix, var_min, var_max +#' } +#' } +#'Given a pair of dataset name and variable name for which we want to know the +#'full path, all the rules that match will be applied from more general to +#'more specific.\cr +#'If there is more than one entry per group that match a given key pair, +#'these will be applied in the order of appearance in the configuration file +#'(top to bottom).\cr\cr +#'An asterisk (*) in any value element will be interpreted as 'leave it as is +#'or take the default value if yet not defined'.\cr +#'The default values are defined in the following reserved variables:\cr +#' $DEFAULT_EXP_MAIN_PATH$, $DEFAULT_EXP_FILE_PATH$, $DEFAULT_NC_VAR_NAME$, +#'$DEFAULT_OBS_MAIN_PATH$, $DEFAULT_OBS_FILE_PATH$, $DEFAULT_SUFFIX$, +#'$DEFAULT_VAR_MIN$, $DEFAULT_VAR_MAX$, \cr +#'$DEFAULT_DIM_NAME_LATITUDES$, $DEFAULT_DIM_NAME_LONGITUDES$, \cr +#'$DEFAULT_DIM_NAME_MEMBERS$\cr\cr +#'Trailing asterisks in an entry are not mandatory. For example\cr +#' ecmwf, .*, /dataset/main/path/, *, *, *, *, *\cr +#'will have the same effect as\cr +#' ecmwf, .*, /dataset/main/path/ \cr\cr +#'A double quote only (") in any key or value element will be interpreted as +#''fill in with the same value as the entry above'. +#' +#'@return +#'ConfigFileOpen() returns a configuration object with all the information for +#' the configuration file mechanism to work.\cr +#'ConfigFileSave() returns TRUE if the file has been saved and FALSE otherwise.\cr +#'ConfigFileCreate() returns nothing. +#' +#'@seealso ConfigApplyMatchingEntries, ConfigEditDefinition, +#' ConfigEditEntry, ConfigFileOpen, ConfigShowSimilarEntries, ConfigShowTable +#'@references +#'[1] \url{https://stat.ethz.ch/R-manual/R-devel/library/base/html/regex.html}\cr +#'[2] \url{http://tldp.org/LDP/abs/html/globbingref.html} +#'@author History: +#' 0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - First version +#' 1.0 - 2015-11 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Removed grid column and storage formats +#'@keywords datagen +#'@examples +#'# Create an empty configuration file +#'config_file <- paste0(tempdir(), "/example.conf") +#'ConfigFileCreate(config_file, confirm = FALSE) +#'# Open it into a configuration object +#'configuration <- ConfigFileOpen(config_file) +#'# Add an entry at the bottom of 4th level of file-per-startdate experiments +#'# table which will associate the experiment "ExampleExperiment2" and variable +#'# "ExampleVariable" to some information about its location. +#'configuration <- ConfigAddEntry(configuration, "experiments", +#' "last", "ExampleExperiment2", "ExampleVariable", +#' "/path/to/ExampleExperiment2/", +#' "ExampleVariable/ExampleVariable_$START_DATE$.nc") +#'# Edit entry to generalize for any variable. Changing variable needs . +#'configuration <- ConfigEditEntry(configuration, "experiments", 1, +#' var_name = ".*", +#' file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") +#'# Now apply matching entries for variable and experiment name and show the +#'# result +#'match_info <- ConfigApplyMatchingEntries(configuration, 'tas', +#' exp = c('ExampleExperiment2'), show_result = TRUE) +#'# Finally save the configuration file. +#'ConfigFileSave(configuration, config_file, confirm = FALSE) +#' +#'@rdname ConfigFileOpen +#'@export ConfigFileOpen <- function(file_path, silent = FALSE, stop = FALSE) { if (!silent) { .message(paste("Reading configuration file:", file_path)) @@ -138,3 +318,78 @@ ConfigFileOpen <- function(file_path, silent = FALSE, stop = FALSE) { experiments = exps, observations = obs)) } + +#'@rdname ConfigFileOpen +#'@export +ConfigFileCreate <- function(file_path, confirm = TRUE) { + success <- ConfigFileSave(list(definitions = list( + DEFAULT_EXP_MAIN_PATH = "$EXP_NAME$", + DEFAULT_EXP_FILE_PATH = "$STORE_FREQ$/$VAR_NAME$_$START_DATE$.nc", + DEFAULT_NC_VAR_NAME = "$VAR_NAME$", + DEFAULT_SUFFIX = "", DEFAULT_VAR_MIN = "", + DEFAULT_VAR_MAX = "", DEFAULT_OBS_MAIN_PATH = "$OBS_NAME$", + DEFAULT_OBS_FILE_PATH = "$STORE_FREQ$/$VAR_NAME$_$YEAR$$MONTH$.nc", + DEFAULT_DIM_NAME_LONGITUDES = "longitude", DEFAULT_DIM_NAME_LATITUDES = "latitude", + DEFAULT_DIM_NAME_MEMBERS = "ensemble")), file_path, confirm = confirm) + if (success) { + .warning("You have just created an empty configuration file. You can edit it with ConfigAddEntry(). You can edit the defaults according to your needs with the functions ConfigFileOpen(), ConfigEditDefinition() and ConfigFileSave() or edit the file manually as specified in ?ConfigFileOpen.") + } +} + +#'@rdname ConfigFileOpen +#'@export +ConfigFileSave <- function(configuration, file_path, confirm = TRUE) { + continue <- TRUE + if (file.exists(file_path)) { + if (confirm) { + while (continue != 'y' && continue != 'n') { + continue <- readline(paste0("WARNING: The configuration file '", file_path, "' already exists. It will be replaced. Continue? (y/n)\n")) + } + continue <- ifelse(continue == 'y', TRUE, FALSE) + } + } + if (continue) { + file_conn <- file(file_path) + file_text <- c( +"# s2dverification configuration file", +"#", +"# Check ?ConfigFileOpen after loading s2dverification for detailed ", +"# documentation on this configuration file.", +"" + ) + + file_text <- c(file_text, + paste(rep("#", nchar("definitions") + 2), collapse = ''), + paste0("!!definitions"), + paste(rep("#", nchar("definitions") + 2), collapse = '') + ) + defaults <- configuration$definitions[grep("^DEFAULT_", names(configuration$definitions))] + definitions <- configuration$definitions[-grep("^DEFAULT_", names(configuration$definitions))] + file_text <- c(file_text, as.vector(paste(names(defaults), unlist(defaults), sep = " = "))) + file_text <- c(file_text, as.vector(paste(names(definitions), unlist(definitions), sep = " = "))) + file_text <- c(file_text, "") + + table_names <- c("experiments", "observations") + for (table_name in table_names) { + if (table_name == "experiments") { + dataset_type <- 'exp' + } else { + dataset_type <- 'obs' + } + file_text <- c(file_text, +"", + paste(rep("#", nchar(table_name) + 11), collapse = ''), + paste0("!!table of ", gsub("_", " ", table_name)), + paste(rep("#", nchar(table_name) + 11), collapse = ''), + paste0("#", dataset_type, "_name, var_name[, ", dataset_type, "_main_path[, ", dataset_type, "_file_path[, nc_var_name[, suffix[, var_min[, var_max]]]]]]") + ) + # Some heavy entry processing still to do here, to put asterisks, empty spaces, double quotes, and reduce options + file_text <- c(file_text, unlist(lapply(configuration[[table_name]], function (x) lapply(x, function (y) paste(unlist(y), collapse = ", "))))) + } + + writeLines(file_text, file_conn) + close(file_conn) + } + + invisible(continue) +} diff --git a/R/ConfigFileSave.R b/R/ConfigFileSave.R deleted file mode 100644 index 7bb719f05e5ae51a2be95a1c4020b4547be4f59a..0000000000000000000000000000000000000000 --- a/R/ConfigFileSave.R +++ /dev/null @@ -1,55 +0,0 @@ -ConfigFileSave <- function(configuration, file_path, confirm = TRUE) { - continue <- TRUE - if (file.exists(file_path)) { - if (confirm) { - while (continue != 'y' && continue != 'n') { - continue <- readline(paste0("WARNING: The configuration file '", file_path, "' already exists. It will be replaced. Continue? (y/n)\n")) - } - continue <- ifelse(continue == 'y', TRUE, FALSE) - } - } - if (continue) { - file_conn <- file(file_path) - file_text <- c( -"# s2dverification configuration file", -"#", -"# Check ?ConfigFileOpen after loading s2dverification for detailed ", -"# documentation on this configuration file.", -"" - ) - - file_text <- c(file_text, - paste(rep("#", nchar("definitions") + 2), collapse = ''), - paste0("!!definitions"), - paste(rep("#", nchar("definitions") + 2), collapse = '') - ) - defaults <- configuration$definitions[grep("^DEFAULT_", names(configuration$definitions))] - definitions <- configuration$definitions[-grep("^DEFAULT_", names(configuration$definitions))] - file_text <- c(file_text, as.vector(paste(names(defaults), unlist(defaults), sep = " = "))) - file_text <- c(file_text, as.vector(paste(names(definitions), unlist(definitions), sep = " = "))) - file_text <- c(file_text, "") - - table_names <- c("experiments", "observations") - for (table_name in table_names) { - if (table_name == "experiments") { - dataset_type <- 'exp' - } else { - dataset_type <- 'obs' - } - file_text <- c(file_text, -"", - paste(rep("#", nchar(table_name) + 11), collapse = ''), - paste0("!!table of ", gsub("_", " ", table_name)), - paste(rep("#", nchar(table_name) + 11), collapse = ''), - paste0("#", dataset_type, "_name, var_name[, ", dataset_type, "_main_path[, ", dataset_type, "_file_path[, nc_var_name[, suffix[, var_min[, var_max]]]]]]") - ) - # Some heavy entry processing still to do here, to put asterisks, empty spaces, double quotes, and reduce options - file_text <- c(file_text, unlist(lapply(configuration[[table_name]], function (x) lapply(x, function (y) paste(unlist(y), collapse = ", "))))) - } - - writeLines(file_text, file_conn) - close(file_conn) - } - - invisible(continue) -} diff --git a/R/ConfigRemoveDefinition.R b/R/ConfigRemoveDefinition.R deleted file mode 100644 index fff12908cb0e2883e2152ce6743948c96e100497..0000000000000000000000000000000000000000 --- a/R/ConfigRemoveDefinition.R +++ /dev/null @@ -1,5 +0,0 @@ -ConfigRemoveDefinition <- function(configuration, name) { - configuration$definitions[[name]] <- NULL - - configuration -} diff --git a/R/ConfigRemoveEntry.R b/R/ConfigRemoveEntry.R deleted file mode 100644 index 579a92bd932a1ddffab800ed15f95ed4f8cc3a60..0000000000000000000000000000000000000000 --- a/R/ConfigRemoveEntry.R +++ /dev/null @@ -1,50 +0,0 @@ -ConfigRemoveEntry <- function(configuration, dataset_type, dataset_name = NULL, var_name = NULL, position = NULL) { - table_name <- dataset_type - if (!is.null(dataset_name) && !is.null(var_name)) { - if (dataset_name == ".*") { - if (var_name == ".*") { - level <- 1 - } else { - level <- 3 - } - } else { - if (var_name == ".*") { - level <- 2 - } else { - level <- 4 - } - } - - position <- which(unlist(lapply(configuration[[table_name]][[level]], "[", 1)) == dataset_name & - unlist(lapply(configuration[[table_name]][[level]], "[", 2)) == var_name)[1] - if (is.na(position)) { - stop("No entry found that matches 'dataset_name' and 'var_name'.") - } - } else { - if (is.null(position)) { - stop("At least ('dataset_name', 'var_name') or 'position' must be specified.") - } - - all_entries <- length(unlist(configuration[[table_name]], recursive = FALSE)) - if (position < 1 || position > all_entries) { - stop("'position' must be in the range [1, # of table entries]") - } - - found <- FALSE - level <- 1 - index_of_first <- 1 - while (!found && level < 5) { - if (position <= (index_of_first + length(configuration[[table_name]][[level]]) - 1)) { - found <- TRUE - } else { - index_of_first <- index_of_first + length(configuration[[table_name]][[level]]) - level <- level + 1 - } - } - position <- position - index_of_first + 1 - } - - configuration[[table_name]][[level]][[position]] <- NULL - - configuration -} diff --git a/R/ConfigShowDefinitions.R b/R/ConfigShowDefinitions.R deleted file mode 100644 index b64772f75f08b3958ab2283c0f55839cc9c56632..0000000000000000000000000000000000000000 --- a/R/ConfigShowDefinitions.R +++ /dev/null @@ -1,5 +0,0 @@ -ConfigShowDefinitions <- function(configuration) { - defaults <- grep("^DEFAULT_", names(configuration$definitions)) - invisible(lapply(as.vector(paste(names(configuration$definitions)[defaults], paste(unlist(configuration$definitions)[defaults], "\n", sep = ''), sep = " = ")), cat)) - invisible(lapply(as.vector(paste(names(configuration$definitions)[-defaults], paste(unlist(configuration$definitions)[-defaults], "\n", sep = ''), sep = " = ")), cat)) -} diff --git a/R/ConfigShowSimilarEntries.R b/R/ConfigShowSimilarEntries.R index e16c35b0d128512e8300178aa1becb8fd6cb8e03..47825b145de953377705d853636b717b4d9fe593 100644 --- a/R/ConfigShowSimilarEntries.R +++ b/R/ConfigShowSimilarEntries.R @@ -1,3 +1,64 @@ +#'Find Similar Entries In Tables Of Datasets +#' +#'These functions help in finding similar entries in tables of supported +#'datasets by comparing all entries with some given information.\cr +#'This is useful when dealing with complex configuration files and not sure +#'if already support certain variables or datasets.\cr +#'At least one field must be provided in ConfigShowSimilarEntries(). +#'Other fields can be unspecified and won't be taken into account. If more +#'than one field is provided, sameness is avreaged over all provided fields +#'and entries are sorted from higher average to lower. +#' +#'@param configuration Configuration object obtained either from +#' ConfigFileCreate() or ConfigFileOpen(). +#'@param dataset_name Optional dataset name to look for similars of. +#'@param var_name Optional variable name to look for similars of. +#'@param main_path Optional main path to look for similars of. +#'@param file_path Optional file path to look for similars of. +#'@param nc_var_name Optional variable name inside NetCDF file to look for similars of. +#'@param suffix Optional suffix to look for similars of. +#'@param varmin Optional variable minimum to look for similars of. +#'@param varmax Optional variable maximum to look for similars of. +#'@param n_results Top 'n_results' alike results will be shown only. Defaults +#' to 10 in ConfigShowSimilarEntries() and to 5 in ConfigShowSimilarVars(). +#' +#'@details +#'Sameness is calculated with string distances as specified by Simon White +#'in [1]. +#' +#'@return These functions return information about the found matches. +#' +#'@seealso ConfigApplyMatchingEntries, ConfigEditDefinition, +#' ConfigEditEntry, ConfigFileOpen, ConfigShowSimilarEntries, ConfigShowTable +#'@references +#'[1] Simon White, string seamness: +#' \url{http://www.catalysoft.com/articles/StrikeAMatch.html} +#'@keywords datagen +#'@author History:\cr +#' 0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - First version\cr +#' 1.0 - 2015-11 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Removed grid column and storage formats +#'@examples +#'# Create an empty configuration file +#'config_file <- paste0(tempdir(), "/example.conf") +#'ConfigFileCreate(config_file, confirm = FALSE) +#'# Open it into a configuration object +#'configuration <- ConfigFileOpen(config_file) +#'# Add an entry at the bottom of 4th level of file-per-startdate experiments +#'# table which will associate the experiment "ExampleExperiment2" and variable +#'# "ExampleVariable" to some information about its location. +#'configuration <- ConfigAddEntry(configuration, "experiments", "last", +#' "ExampleExperiment2", "ExampleVariable", +#' "/path/to/ExampleExperiment2/", +#' "ExampleVariable/ExampleVariable_$START_DATE$.nc") +#'# Edit entry to generalize for any variable. Changing variable needs . +#'configuration <- ConfigEditEntry(configuration, "experiments", 1, +#' var_name = "Var.*", +#' file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") +#'# Look for similar entries +#'ConfigShowSimilarEntries(configuration, dataset_name = "Exper", +#' var_name = "Vari") +#' +#'@export ConfigShowSimilarEntries <- function(configuration, dataset_name = NULL, var_name = NULL, main_path = NULL, file_path = NULL, nc_var_name = NULL, suffix = NULL, varmin = NULL, varmax = NULL, n_results = 10) { ## Simon White: http://www.catalysoft.com/articles/StrikeAMatch.html getBigrams <- function(str) { diff --git a/R/ConfigShowTable.R b/R/ConfigShowTable.R index 0f8837e98e8a04bb25c383755d86a9f420de0b85..2610e8836b075aedde67d3574ea0d1296295a65d 100644 --- a/R/ConfigShowTable.R +++ b/R/ConfigShowTable.R @@ -1,3 +1,48 @@ +#'Show Configuration Tables And Definitions +#' +#'These functions show the tables of supported datasets and definitions in a +#'configuration object obtained via ConfigFileCreate() or ConfigFileOpen(). +#' +#'@param configuration Configuration object obtained from ConfigFileCreate() +#' or ConfigFileOpen(). +#'@param dataset_type In ConfigShowTable(), 'dataset_type' tells whether the +#' table to show is of experimental datasets or of observational datasets. +#' Can take values 'experiments' or 'observations'. +#'@param line_numbers 'line_numbers' is an optional vector of numbers as long +#' as the number of entries in the specified table. Intended for internal use. +#' +#'@seealso [ConfigApplyMatchingEntries()], [ConfigEditDefinition()], +#' [ConfigEditEntry()], [ConfigFileOpen()], [ConfigShowSimilarEntries()], +#' [ConfigShowTable()]. +#'@keywords datagen +#'@author History:\cr +#' 0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - First version\cr +#' 1.0 - 2015-11 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Removed grid column and storage formats +#'@return These functions return nothing. +#' +#'@examples +#'# Create an empty configuration file +#'config_file <- paste0(tempdir(), "/example.conf") +#'ConfigFileCreate(config_file, confirm = FALSE) +#'# Open it into a configuration object +#'configuration <- ConfigFileOpen(config_file) +#'# Add an entry at the bottom of 4th level of file-per-startdate experiments +#'# table which will associate the experiment "ExampleExperiment2" and variable +#'# "ExampleVariable" to some information about its location. +#'configuration <- ConfigAddEntry(configuration, "experiments", "last", +#' "ExampleExperiment2", "ExampleVariable", +#' "/path/to/ExampleExperiment2/", +#' "ExampleVariable/ExampleVariable_$START_DATE$.nc") +#'# Edit entry to generalize for any variable. Changing variable needs . +#'configuration <- ConfigEditEntry(configuration, "experiments", 1, +#' var_name = ".*", +#' file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") +#'# Show tables, lists and definitions +#'ConfigShowTable(configuration, 'experiments') +#'ConfigShowDefinitions(configuration) +#' +#'@rdname ConfigShowTable +#'@export ConfigShowTable <- function(configuration, dataset_type, line_numbers = NULL) { table_name <- dataset_type header <- paste("| Matches in", gsub("_", " ", table_name), "|") @@ -25,3 +70,10 @@ ConfigShowTable <- function(configuration, dataset_type, line_numbers = NULL) { } )) } +#'@rdname ConfigShowTable +#'@export +ConfigShowDefinitions <- function(configuration) { + defaults <- grep("^DEFAULT_", names(configuration$definitions)) + invisible(lapply(as.vector(paste(names(configuration$definitions)[defaults], paste(unlist(configuration$definitions)[defaults], "\n", sep = ''), sep = " = ")), cat)) + invisible(lapply(as.vector(paste(names(configuration$definitions)[-defaults], paste(unlist(configuration$definitions)[-defaults], "\n", sep = ''), sep = " = ")), cat)) +} diff --git a/R/Consist_Trend.R b/R/Consist_Trend.R index 48f8999fec140ed4ddb091cd6144a490ae234d55..827440fc8fedb0b093c6055686df6c65d88acca5 100644 --- a/R/Consist_Trend.R +++ b/R/Consist_Trend.R @@ -1,3 +1,71 @@ +#'Computes Trends Using Only Model Data For Which Observations Are Available +#' +#'Computes the trend coefficients for a time series by least square fitting, +#'together with the associated error interval for both the observational and +#'model data.\cr +#'Provides also the detrended observational and modeled data.\cr +#'By default, the trend is computed along the second dimension of the input +#'array, which is expected to be the start date dimension. For arrays +#'containing multiple model members, the user will first have to calculate +#'the ensemble average using \code{Mean1Dim()} or elsewhise (see the example). +#' +#'@param var_exp Ensemble mean of model hindcasts with dimensions:\cr +#' c(nmod/nexp, nsdates, nltime) up to\cr +#' c(nmod/nexp, nsdates, nltime, nlevel, nlat, nlon) +#'@param var_obs Ensemble mean of observational data with dimensions:\cr +#' c(nobs, nsdates, nltime) up to\cr +#' c(nobs, nsdates, nltime, nlevel, nlat, nlon)\cr +#' Dimensions 2 to 6 should be the same as var_exp. +#'@param interval Number of months/years between 2 start dates. Default = 1. +#' The trends will be provided respectively in field unit per month or per year. +#' +#'@return +#'\item{$trend}{ +#' Trend coefficients of model and observational data with dimensions:\cr +#' c(nmod/nexp + nobs, 3, nltime) up to\cr +#' c(nmod/nexp + nobs, 3, nltime, nlevel, nlat, nlon)\cr +#' The length 3 dimension corresponds to the lower limit of the 95\% +#' confidence interval, the slope of the trends and the upper limit of the +#' 95\% confidence interval. +#' } +#'\item{$detrendedmod}{ +#' Same dimensions as var_exp with linearly detrended values of var_exp +#' along the second = start date dimension. +#' } +#'\item{$detrendedobs}{ +#' Same dimensions as var_exp with linearly detrended values of var_obs +#' along the second = start date dimension. +#' } +#' +#'@keywords datagen +#'@author History:\cr +#' 0.1 - 2011-11 (V. Guemas, \email{vguemas@@ic3.cat}) - Original code\cr +#' 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to R CRAN +#'@examples +#'#'# Load sample data as in Load() example: +#'example(Load) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'ano_exp <- Ano(sampleData$mod, clim$clim_exp) +#'ano_obs <- Ano(sampleData$obs, clim$clim_obs) +#'runmean_months <- 12 +#'dim_to_smooth <- 4 # Smooth along lead-times +#'smooth_ano_exp <- Smoothing(ano_exp, runmean_months, dim_to_smooth) +#'smooth_ano_obs <- Smoothing(ano_obs, runmean_months, dim_to_smooth) +#'dim_to_mean <- 2 # Mean along members +#'years_between_startdates <- 5 +#'trend <- Consist_Trend(Mean1Dim(smooth_ano_exp, dim_to_mean), +#' Mean1Dim(smooth_ano_obs, dim_to_mean), +#' years_between_startdates) +#' +#'PlotVsLTime(trend$trend, toptitle = "trend", ytitle = "K/(5 years)", +#' monini = 11, limits = c(-0.8, 0.8), listexp = c('CMIP5 IC3'), +#' listobs = c('ERSST'), biglab = FALSE, hlines = c(0), +#' fileout = 'tos_consist_trend.eps') +#'PlotAno(InsertDim(trend$detrendedmod,2,1), InsertDim(trend$detrendedobs,2,1), +#' startDates, "Detrended tos anomalies", ytitle = 'K', +#' legends = 'ERSST', biglab = FALSE, fileout = 'tos_detrended_ano.eps') +#' +#'@export Consist_Trend <- function(var_exp, var_obs, interval = 1) { # # Enlarge the number of dimensions of var_exp and var_obs to 6 if necessary diff --git a/R/Corr.R b/R/Corr.R index 4654db2ced466e1ff53be85824cf9f0c4b5725bc..18ae9b1455f4445a5112b0ba462d64bad7a3974c 100644 --- a/R/Corr.R +++ b/R/Corr.R @@ -1,3 +1,109 @@ +#'Computes the correlation coefficient between an array of forecasts and their corresponding observations +#' +#'Calculates the correlation coefficient (Pearson, Kendall or Spearman) for +#'an array of forecasts and observations. The input should be an array with +#'dimensions c(no. of datasets, no. of start dates, no. of forecast times, +#'no. of lons, no. of lats.), where the longitude and latitude dimensions are +#'optional. The correlations are computed along the poscor dimension which +#'should correspond to the startdate dimension. If compROW is given, the +#'correlations are computed only if rows along the compROW dimension are +#'complete between limits[1] and limits[2], i.e. there are no NAs between +#'limits[1] and limits[2]. This option can be activated if the user wishes to +#'account only for the forecasts for which observations are available at all +#'leadtimes. \cr +#'Default: limits[1] = 1 and limits[2] = length(compROW dimension).\cr +#'The confidence interval is computed by a Fisher transformation.\cr +#'The significance level relies on a one-sided student-T distribution.\cr +#'We can modifiy the treshold of the test modifying siglev (default value=0.95).\cr\cr +#'.Corr calculates the correlation between the ensemble mean and the +#'observations, using an N by M matrix (exp) of forecasts and a vector of +#'observations (obs) as input. +#' +#'@param var_exp Array of experimental data. +#'@param var_obs Array of observational data, same dimensions as var_exp +#' except along posloop dimension, where the length can be nobs instead of nexp. +#'@param posloop Dimension nobs and nexp. +#'@param poscor Dimension along which correlation are to be computed (the +#' dimension of the start dates). +#'@param compROW Data taken into account only if (compROW)th row is complete. +#' Default = NULL. +#'@param limits Complete between limits[1] & limits[2]. Default = NULL. +#'@param siglev Significance level. Default = 0.95. +#'@param method Type of correlation: 'pearson', 'spearman' or 'kendall'. +#' Default='pearson' +#'@param conf Whether to compute confidence intervals (default = 'TRUE') or +#' not (FALSE). +#'@param pval Whether to compute statistical significance p-value (default = 'TRUE') +#' or not (FALSE). +#'@param exp N by M matrix of N forecasts from M ensemble members. +#'@param obs Vector of the corresponding observations of length N. +#' +#'@return +#'Corr: Array with dimensions :\cr +#'c(# of datasets along posloop in var_exp, # of datasets along posloop in +#'var_obs, 4, all other dimensions of var_exp & var_obs except poscor).\cr +#'The third dimension, of length 4 maximum, contains to the lower limit of +#'the 95\% confidence interval, the correlation, the upper limit of the 95\% +#'confidence interval and the 95\% significance level given by a one-sided +#'T-test. If the p-value is disabled via \code{pval = FALSE}, this dimension +#'will be of length 3. If the confidence intervals are disabled via +#'\code{conf = FALSE}, this dimension will be of length 2. If both are +#'disabled, this will be of length 2. \cr\cr +#'.Corr: +#' \itemize{ +#' \item{$corr}{The correlation statistic.} +#' \item{$p_val}{Corresponds to the p values for the \code{siglev}\% +#' (only present if \code{pval = TRUE}) for the correlation.} +#' \item{$conf_low}{Corresponds to the upper limit of the \code{siglev}\% +#' (only present if \code{conf = TRUE}) for the correlation.} +#' \item{$conf_high}{Corresponds to the lower limit of the \code{siglev}\% +#' (only present if \code{conf = TRUE}) for the correlation.} +#' } +#' +#'@keywords datagen +#'@author History:\cr +#' 0.1 - 2011-04 (V. Guemas, \email{vguemas@@bsc.es}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@bsc.es}) - Formatting to R CRAN\cr +#'1.1 - 2014-10 (M. Menegoz, \email{martin.menegoz@@bsc.es}) - Adding siglev argument\cr +#'1.2 - 2015-03 (L.P. Caron, \email{louis-philippe.caron@@bsc.es}) - Adding method argument\cr +#'1.3 - 2017-02 (A. Hunter, \email{alasdair.hunter@@bsc.es}) - Adapted to veriApply() +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'ano_exp <- Ano(sampleData$mod, clim$clim_exp) +#'ano_obs <- Ano(sampleData$obs, clim$clim_obs) +#'runmean_months <- 12 +#'dim_to_smooth <- 4 +#'# Smooth along lead-times +#'smooth_ano_exp <- Smoothing(ano_exp, runmean_months, dim_to_smooth) +#'smooth_ano_obs <- Smoothing(ano_obs, runmean_months, dim_to_smooth) +#'dim_to_mean <- 2 # Mean along members +#'required_complete_row <- 3 # Discard start dates which contain any NA lead-times +#'leadtimes_per_startdate <- 60 +#'corr <- Corr(Mean1Dim(smooth_ano_exp, dim_to_mean), +#' Mean1Dim(smooth_ano_obs, dim_to_mean), +#' compROW = required_complete_row, +#' limits = c(ceiling((runmean_months + 1) / 2), +#' leadtimes_per_startdate - floor(runmean_months / 2))) +#'PlotVsLTime(corr, toptitle = "correlations", ytitle = "correlation", +#' monini = 11, limits = c(-1, 2), listexp = c('CMIP5 IC3'), +#' listobs = c('ERSST'), biglab = FALSE, hlines = c(-1, 0, 1), +#' fileout = 'tos_cor.eps') +#' +#'# The following example uses veriApply combined with .Corr instead of Corr +#' \dontrun{ +#'require(easyVerification) +#'Corr2 <- s2dverification:::.Corr +#'corr2 <- veriApply("Corr2", +#' smooth_ano_exp, +#' # see ?veriApply for how to use the 'parallel' option +#' Mean1Dim(smooth_ano_obs, dim_to_mean), +#' tdim = 3, ensdim = 2) +#' } +#'@rdname Corr +#'@importFrom stats cor pt qnorm +#'@export Corr <- function(var_exp, var_obs, posloop = 1, poscor = 2, compROW = NULL, limits = NULL, siglev = 0.95, method = 'pearson', conf = TRUE, pval = TRUE) { @@ -124,6 +230,9 @@ Corr <- function(var_exp, var_obs, posloop = 1, poscor = 2, compROW = NULL, CORR } +#'@rdname Corr +#'@importFrom stats cor pt qnorm +#'@export .Corr <- function(exp, obs, siglev = 0.95, method = 'pearson', conf = TRUE, pval = TRUE) { diff --git a/R/EOF.R b/R/EOF.R index 0ad1a97c0766d3fd6268a3d2485c6d4c55bdae7c..6ed8c6f751bfba8c52ddfdfd4fbcda87d64bbdee 100644 --- a/R/EOF.R +++ b/R/EOF.R @@ -1,3 +1,110 @@ +#'Area-Weighted Empirical Orthogonal Function Analysis Using SVD +#' +#'Performs an area-weighted EOF analysis using SVD based on a covariance matrix +#'by default, based on the correlation matrix if \code{corr} argument is set to +#'\code{TRUE}. +#' +#'@param ano Array of anomalies with dimensions (number of timesteps, +#' number of latitudes, number of longitudes). +#'@param lon Vector of longitudes of \code{ano}. +#'@param lat Vector of latitudes of \code{ano}. +#'@param neofs Number of modes to be kept. Default = 15. +#'@param corr Whether to base on a correlation matrix (\code{TRUE}) or on a +#' covariance matrix (default, \code{FALSE}). +#' +#'@return +#'\item{EOFs}{ +#' An array of EOF patterns normalized to 1 (unitless) with dimensions +#' (number of modes, number of latitudes, number of longitues). +#' Multiplying \code{EOFs} by \code{PCs} gives the original reconstructed field. +#'} +#'\item{PCs}{ +#' An array of pincipal components with the units of the original field to +#' the power of 2, with dimensions (number of time steps, number of modes). +#' \code{PCs} contains already the percentage of explained variance so, +#' to reconstruct the original field it's only needed to multiply \code{EOFs} +#' by \code{PCs}. +#'} +#'\item{var}{ +#' Percentage (%) of variance fraction of total variance explained by each +#' mode (number of modes). +#'} +#'\item{mask}{ +#' Mask with dimensions (number of latitudes, number of longitudes). +#'} +#'\item{wght}{ +#' Weights with dimensions (number of latitudes, number of longitudes). +#'} +#' +#'@seealso ProjectField, NAO, PlotBoxWhisker +#'@keywords datagen +#'@author History:\cr +#' 0.1 - 2012-10 (F. Lienert, \email{fabian.lienert@@ic3.cat}) - Original +#' code, inspired by R. Benestad's EOF() in R package clim.pact.\cr +#' 0.2 - 2014-03 (Lauriane Batte, \email{lauriane.batte@@ic3.cat}) - Bug-fixes:\cr +#' 1- Reversion of latitudes in the weights\cr +#' 2- Correlation matrix was used instead of covariance\cr +#' 3- Double use of the weights\cr +#'0.3 - 2014-03 (Virginie Guemas, \email{virginie.guemas@@bsc.es}) - Bug-fixes:\cr +#' 1- Weight computation - division by sum of cos(lat)\cr +#' 2- Shuffling of EOFs in EOF.2 intermediate vector\cr +#' 3- Crash when neofs = 1 sorted out\cr +#' 4- Crash when neofs > nt sorted out\cr +#'0.4 - 2014-03 (Lauriane Batte, \email{lauriane.batte@@ic3.cat}) - Fixes:\cr +#' 1- BIG cleanup of code and clarification\cr +#' 2- Reduction of the number of transpositions and associated bug-fixes\cr +#' 4- Remove of the obsolete LINPACK options\cr +#'0.5 - 2014-04 (Virginie Guemas, \email{virginie.guemas@@bsc.es}) - Fixes:\cr +#' 1- Bug-fix in dimensions handling EOF composition restitutes now the +#'original field in all cases\cr +#' 2- Simplification of the convention transpose\cr +#' 3- Options to use the correlation matrix rather than the +#'covariance matrix\cr +#' 4- Security checks\cr +#' 5- New normalization of PCs so that PC*EOF only reconstruct the +#'original file\cr +#' 6- Weights = sqrt(cos(lat)) for ano so that covariance matrice +#'weighted by cos(lat)\cr +#' 7- Division of EOF by weights so that the reconstruction is simply +#'EOF * PC\cr +#'1.0 - 2016-03 (N. Manubens, \email{nicolau.manubens@@bsc.es}) - Formatting to R CRAN +#' +#'@examples +#'# See examples on Load() to understand the first lines in this example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' leadtimemin = 1, leadtimemax = 4, output = 'lonlat', +#' latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' leadtimemin = 1, +#' leadtimemax = 4, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'# This example computes the EOFs along forecast horizons and plots the one that +#'# explains the greatest amount of variability. The example data is very low +#'# resolution so it does not make a lot of sense. +#'ano <- Ano_CrossValid(sampleData$mod, sampleData$obs) +#'eof <- EOF(Mean1Dim(ano$ano_exp, 2)[1, , 1, , ], sampleData$lon, sampleData$lat) +#'PlotEquiMap(eof$EOFs[1, , ], sampleData$lon, sampleData$lat) +#' +#'@importFrom stats sd +#'@export EOF <- function(ano, lon, lat, neofs = 15, corr = FALSE) { # Checking ano if (!is.numeric(ano) || !is.array(ano)) { diff --git a/R/Enlarge.R b/R/Enlarge.R index 16736c656d7459bebea465b9ce0a3c1d4dfdd624..5ebd28c2f1cb0c3eeae813f5780f5c4c79638255 100644 --- a/R/Enlarge.R +++ b/R/Enlarge.R @@ -1,3 +1,22 @@ +#'Extends The Number Of Dimensions of A Matrix +#' +#'Extends the number of dimensions of var to numdims (the added dimensions +#'have length 1). +#' +#'@param var Matrix to be extended. +#'@param numdims Output number of dimensions. +#' +#'@return Output number of dimensions. +#' +#'@keywords datagen +#'@author History:\cr +#' 0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@@ic3.cat}) - Original code\cr +#' 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to R CRAN\cr +#' 1.1 - 2015-03 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Improved\cr +#'@examples +#'data <- array(1, c(2, 2, 3)) +#'print(dim(Enlarge(data, 5))) +#'@export Enlarge <- function(var, numdims) { if (is.numeric(var) || is.logical(var)) { if (is.null(dim(var))) { diff --git a/R/Eno.R b/R/Eno.R index 0f63aafa9ed5310b1b908f22989988488a809a8e..877710cb9a1769378ac81c480fcaff5b78459b46 100644 --- a/R/Eno.R +++ b/R/Eno.R @@ -1,3 +1,54 @@ +#'Computes Effective Sample Size With Classical Method +#' +#'Computes the effective number of independent values along the posdim +#'dimension of a matrix.\cr +#'This effective number of independent observations can be used in +#'statistical/inference tests.\cr +#'Based on eno function from Caio Coelho from rclim.txt. +#' +#'@param obs Matrix of any number of dimensions up to 10. +#'@param posdim Dimension along which to compute the effective sample size. +#' +#'@return Same dimensions as var but without the posdim dimension. +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2011-05 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to R CRAN +#'@examples +#'# See examples on Load() to understand the first lines in this example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'exp <- list( +#' name = 'experiment', +#' path = file.path(data_path, 'model/$EXP_NAME$/monthly_mean', +#' '$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATES$.nc') +#' ) +#'obs <- list( +#' name = 'observation', +#' path = file.path(data_path, 'observation/$OBS_NAME$/monthly_mean', +#' '$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') +#' ) +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(exp), list(obs), startDates, +#' leadtimemin = 1, leadtimemax = 4, output = 'lonlat', +#' latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'sampleData$mod <- Season(sampleData$mod, 4, 11, 1, 12) +#'eno <- Eno(sampleData$mod[1, 1, , 1, , ], 1) +#'PlotEquiMap(eno, sampleData$lon, sampleData$lat) +#' +#'@importFrom stats acf na.pass +#'@export Eno <- function(obs, posdim) { dimsvar <- dim(obs) if (is.null(dimsvar)) { diff --git a/R/EnoNew.R b/R/EnoNew.R index c59e75635c5a794988bcebcba7741e0c901145e9..ebd743626aa37984af6fb621dd3466d6c301451a 100644 --- a/R/EnoNew.R +++ b/R/EnoNew.R @@ -1,3 +1,59 @@ +#'Computes Effective Sample Size Following Guemas et al, BAMS, 2013b +#' +#'This function computes the effective number of independent values in the +#'xdata array following the method described in +#'Guemas V., Auger L., Doblas-Reyes F., JAMC, 2013. \code{EnoNew} provides +#'similar functionality to \code{Eno} but with the added options to remove +#'the linear trend or filter the frequency. +#' +#'@param xdata A numeric vector. +#'@param detrend Should the linear trend be removed from the data prior to +#' the estimation of the equivalent number of independent values. +#'@param filter Should a filtering of the frequency peaks be applied prior +#' to the estimation of the equivalent number of independant data. +#' +#'@references +#'Guemas V, Auger L, Doblas-Reyes FJ, Rust H, Ribes A, 2014, Dependencies in +#' Statistical Hypothesis Tests for Climate Time Series. Bulletin of the +#' American Meteorological Society, 95 (11), 1666-1667. +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2012-06 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +#'@examples +#'# See examples on Load() to understand the first lines in this example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'exp <- list( +#' name = 'experiment', +#' path = file.path(data_path, 'model/$EXP_NAME$/monthly_mean', +#' '$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATES$.nc') +#' ) +#'obs <- list( +#' name = 'observation', +#' path = file.path(data_path, 'observation/$OBS_NAME$/monthly_mean', +#' '$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') +#' ) +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(exp), list(obs), startDates, +#' leadtimemin = 1, leadtimemax = 4, output = 'lonlat', +#' latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' leadtimemin = 1, +#' leadtimemax = 4, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'eno <- EnoNew(sampleData$mod[1, 1, , 1, 2, 3]) +#'print(eno) +#' +#'@export EnoNew <- function(xdata, detrend = FALSE, filter = FALSE) { alpha <- Alpha(xdata, detrend, filter) s <- 0 diff --git a/R/Filter.R b/R/Filter.R index bb5eba31f8848f1b7d566a5ca4847b12c1838f21..42c847f91cd017086576b2d0d423600d94afb5aa 100644 --- a/R/Filter.R +++ b/R/Filter.R @@ -1,3 +1,40 @@ +#'Filter Frequency Peaks From An Array +#' +#'This function filters out the selected frequency from a time series.\cr +#'The filtering is performed by dichotomy, seeking for a frequency around +#'the parameter \code{freq} and the phase that maximizes the signal to subtract +#'from the time series.\cr +#'The maximization of the signal to subtract relies on a minimization of the +#'mean square differences between the time series (xdata) and the cosine of +#'the specified frequency and phase. +#' +#'@param xdata Array to be filtered. +#'@param freq Frequency to filter. +#' +#'@return Filtered Array. +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2012-02 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr +#'1.0 - 2012-02 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'ensmod <- Mean1Dim(sampleData$mod, 2) +#'for (jstartdate in 1:3) { +#' spectrum <- Spectrum(ensmod[1, jstartdate, ]) +#' for (jlen in 1:dim(spectrum)[1]) { +#' if (spectrum[jlen, 2] > spectrum[jlen, 4]) { +#' ensmod[1, jstartdate, ] <- Filter(ensmod[1, jstartdate, ], +#' spectrum[jlen, 1]) +#' } +#' } +#'} +#'PlotAno(InsertDim(ensmod, 2, 1), sdates = startDates, fileout = +#' 'filtered_ensemble_mean.eps') +#' +#'@importFrom stats lm +#'@export Filter <- function(xdata, freq) { fac1 <- 1 fac2 <- 1 diff --git a/R/FitAcfCoef.R b/R/FitAcfCoef.R index 1561f386f67d129be1bb4df7ad1dad376999311d..311761ec9be98de856d632082acbc90c855f2264 100644 --- a/R/FitAcfCoef.R +++ b/R/FitAcfCoef.R @@ -1,3 +1,31 @@ +#'Fits an AR1 AutoCorrelation Function Using the Cardano Formula +#' +#'This function finds the minimum point of the fourth order polynom +#'(a - x)2 + 0.25(b - x2)2 written to fit the two autoregression coefficients +#'a and b.\cr +#'A consequence of the Cardano formula is that, provided a and b are in [0 1], +#'the problem is well posed, delta > 0 and there is only one minimum.\cr\cr +#'This function is called in Alpha() to minimize the mean square differences +#'between the theoretical autocorrelation function of an AR1 and the first +#'guess of the estimated autocorrelation function estacf, using only the +#'first two lags. +#' +#'@param a Coefficient a : first estimate of the autocorrelation at lag 1. +#'@param b Coefficient b : first estimate of the autocorrelation at lag 2. +#' +#'@return Best estimate of the autocorrelation at lag 1. +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2012-06 (L. Auger, \email{ludovic.auger@meteo.fr}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN +#'@examples +#'series <- GenSeries(1000, 0.35, 2, 1) +#'estacf <- acf(series[951:1000], plot = FALSE)$acf +#'alpha <- FitAcfCoef(max(estacf[2], 0), max(estacf[3], 0)) +#'print(alpha) +#' +#'@export FitAcfCoef <- function(a, b) { if ((a < 0) || (a > 1) || (b < 0) || (b > 1)) { stop("One of the coefficients is outside the [0 1] interval"); diff --git a/R/FitAutocor.R b/R/FitAutocor.R index 1818b09d12d1ea013b921d94a453e9c221eacdd3..903063b93d4ea1a8657f1b1d4557ac6feef5085f 100644 --- a/R/FitAutocor.R +++ b/R/FitAutocor.R @@ -1,3 +1,27 @@ +#'Fits an AR1 Autocorrelation Function Using Dichotomy +#' +#'This function fits the theoretical autocorrelation function of an AR1 to +#'the first guess of the estimated autocorrelation function estacf containing +#'any number of lags. The fitting relies on a dichotomial minimisation of the +#'mean square differences between both autocorrelation functions. It returns +#'the autocorrelation at lag 1 of the fitted AR1 process. +#' +#'@param estacf First guess for the autocorrelation function. +#'@param window Interval in which the autocorrelation at lag 1 should be found. +#'@param prec Precision to which the autocorrelation function at lag 1 is to be estimated. +#' +#'@return Best estimate of the autocorrelation at lag 1. +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2012-02 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN +#'@examples +#'series <- GenSeries(1000, 0.35, 2, 1) +#'estacf <- acf(series[951:1000], plot = FALSE)$acf +#'alpha <- FitAutocor(estacf, c(-1, 1), 0.01) +#'print(alpha) +#'@export FitAutocor <- function(estacf, window = c(-1, 1), prec = 0.01) { nacf <- length(estacf) alpha <- mean(window) diff --git a/R/GenSeries.R b/R/GenSeries.R index a4497c201f766d02ee9a8c42c0cb813b65227320..402170a99586e96fc87f828ec632625e9852fc59 100644 --- a/R/GenSeries.R +++ b/R/GenSeries.R @@ -1,3 +1,26 @@ +#'Generates An AR1 Time Series +#' +#'This function generates AR1 processes containing n data points, where alpha +#'is the autocorrelation at lag 1, and the mean and standard deviation are +#'specified by the mean and std arguments. +#' +#'@param n Length of the timeseries to be generated. +#'@param alpha Autocorrelation at lag 1. +#'@param mean Mean of the data. +#'@param std Standard deviation of the data. +#' +#'@return AR1 timeseries. +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2012-04 (L. Auger, \email{ludovic.auger@meteo.fr}) - Original code\cr +#'1.0 - 2012-04 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN +#'@examples +#'series <- GenSeries(1000, 0.35, 2, 1) +#'plot(series, type = 'l') +#' +#'@importFrom stats rnorm +#'@export GenSeries <- function(n, alpha, mean, std) { res <- vector("numeric", n) x <- mean diff --git a/R/Histo2Hindcast.R b/R/Histo2Hindcast.R index b8a312c7a8784b9e7085db3abdf6badb02d3e313..cb93ae8606ce81bbd32b69b4883e290e025ad732 100644 --- a/R/Histo2Hindcast.R +++ b/R/Histo2Hindcast.R @@ -1,3 +1,68 @@ +#'Chunks Long Simulations For Comparison With Hindcasts +#' +#'This function reorganizes a long run (historical typically) with only one +#'start date into chunks corresponding to a set of start dates. The expected +#'input structure is the one output from \code{Load()} with 4 to 7 dimensions. +#' +#'@param varin Array of model or observational data with dimensions:\cr +#' c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltimes) up to\cr +#' c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltimes, nlevel, nlat, nlon) +#'@param sdatesin Start date of the input matrix 'YYYYMMDD'. +#'@param sdatesout List of start dates of the output matrix +#' c('YYYYMMDD', 'YYYYMMDD', ...). +#'@param nleadtimesout Number of leadtimes in the output matrix. +#' +#'@return An array with the same number of dimensions as varin, the same +#' dimensions 1 and 2 and potentially the same dimensions 5 to 7. Dimensions +#' 3 and 4 are set by the arguments sdatesout and nleadtimesout. +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2012-11 (V. Guemas, \email{vguemas@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN +#'@examples +#'# See examples on Load() to understand the first lines in this example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'exp <- list( +#' name = 'experiment', +#' path = file.path(data_path, 'model/$EXP_NAME$/monthly_mean', +#' '$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATES$.nc') +#' ) +#'obs <- list( +#' name = 'observation', +#' path = file.path(data_path, 'observation/$OBS_NAME$/monthly_mean', +#' '$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') +#' ) +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(exp), list(obs), startDates, +#' leadtimemin = 1, leadtimemax = 4, output = 'lonlat', +#' latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19901101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' leadtimemin = 1, +#' leadtimemax = 4, +#' output = 'areave', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#' +#' +#'start_dates_out <- c('19901101', '19911101', '19921101', '19931101', '19941101') +#'leadtimes_per_startdate <- 12 +#'experimental_data <- Histo2Hindcast(sampleData$mod, startDates[1], +#' start_dates_out, leadtimes_per_startdate) +#'observational_data <- Histo2Hindcast(sampleData$obs, startDates[1], +#' start_dates_out, leadtimes_per_startdate) +#'PlotAno(experimental_data, observational_data, start_dates_out, +#' toptitle = paste('anomalies reorganized into shorter chunks'), +#' ytitle = 'K', fileout='tos_histo2hindcast.eps') +#' +#'@export Histo2Hindcast <- function(varin, sdatesin, sdatesout, nleadtimesout) { # # Input parameters diff --git a/R/IniListDims.R b/R/IniListDims.R index b438faaccdb3fa82b399376a509efefdbce456c4..825ccacc666400e5f65f4b30699ba6db132894ec 100644 --- a/R/IniListDims.R +++ b/R/IniListDims.R @@ -1,3 +1,32 @@ +#'Creates A List Of Integer Ranges +#' +#'This function generates a list of arrays containing integers greater than or +#'equal to 1. This list of arrays is used in other functions as a list of +#'indices of the elements of the matrices. +#' +#'@param dims The dimensions of a matrix for which we need the possible +#' indices for each dimension. For exemple, if the dimensions sent are +#' c(3,2,5), the following list of arrays will be generated:\cr +#' list(c(1:3), c(1:2), c(1:5)). +#'@param lenlist 'lenlist' is the length of the list because the list will +#' be complemented above length(dims) by arrays of length 1.\cr +#' For example, if lenlist is set to 7, the previous list of arrays will be +#' extended to:\cr +#' list(c(1:3), c(1:2), c(1:5), 1, 1, 1, 1). +#' +#'@return A list with lenlist elements, each with arrays with integers from 1 +#' to the numbers in dims array and with only 1 for the dimensions above +#' length(dims). +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2011-04 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to R CRAN\cr +#'1.1 - 2015-03 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Improved +#'@examples +#'indices <- IniListDims(c(2, 2, 4, 3), 6) +#'print(indices) +#'@export IniListDims <- function(dims, lenlist) { indices <- as.list(rep(1, lenlist)) for (jdim in 1:min(length(dims), lenlist)) { diff --git a/R/InsertDim.R b/R/InsertDim.R index 04bc12707bd337f9c93b19879f9a699c37cae1d0..2e7a9b82e9f5ac8131bb57f58a2c5fd888cdfbe7 100644 --- a/R/InsertDim.R +++ b/R/InsertDim.R @@ -1,3 +1,26 @@ +#'Adds A Dimension To An Array +#' +#'Inserts an extra dimension into an array at position 'posdim' with length +#''lendim' and which correspond to 'lendim' repetitions of the 'var' array. +#' +#'@param var Matrix to which a dimension should be added. +#'@param posdim Position of the new dimension. +#'@param lendim Length of the new dimension. +#' +#'@return Matrix with the added dimension. +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to R CRAN\cr +#'1.1 - 2015-03 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Improvements +#'@examples +#'a <- array(rnorm(15), dim = c(3, 1, 5, 1)) +#'print(dim(a)) +#'print(dim(a[, , , ])) +#'print(dim(InsertDim(InsertDim(a[, , , ], 2, 1), 4, 1))) +#' +#'@export InsertDim <- function(var, posdim, lendim) { if (is.numeric(var) || is.logical(var)) { dimsvar <- dim(var) diff --git a/R/LeapYear.R b/R/LeapYear.R index 3e8709227c4b32a9b8d6578a4c8adbbb86d71983..89865604465020d1014fb8ecd55c17f2f9231083 100644 --- a/R/LeapYear.R +++ b/R/LeapYear.R @@ -1,3 +1,22 @@ +#'Checks Whether A Year Is Leap Year +#' +#'This function tells whether a year is a leap year or not. +#' +#'@param year A numeric value indicating the year in the Gregorian calendar. +#' +#'@return Boolean telling whether the year is a leap year or not. +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2011-03 (V. Guemas, \email{vguemas@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN +#'@examples +#'print(LeapYear(1990)) +#'print(LeapYear(1991)) +#'print(LeapYear(1992)) +#'print(LeapYear(1993)) + +#'@export LeapYear <- function(year) { leap <- FALSE if (year %% 4 == 0) { diff --git a/R/Load.R b/R/Load.R index 5cebec71106778ac3e1205aa6f432f332e552853..e17f3cfa683dbaf839d5f3cb022e091bec0352ff 100644 --- a/R/Load.R +++ b/R/Load.R @@ -1,3 +1,846 @@ +#'Loads Experimental And Observational Data +#' +#'This function loads monthly or daily data from a set of specified +#'experimental datasets together with data that date-corresponds from a set +#'of specified observational datasets. See parameters 'storefreq', +#''sampleperiod', 'exp' and 'obs'.\cr\cr +#'A set of starting dates is specified through the parameter 'sdates'. Data of +#'each starting date is loaded for each model. +#'\code{Load()} arranges the data in two arrays with a similar format both +#'with the following dimensions: +#' \enumerate{ +#' \item{The number of experimental datasets determined by the user through +#' the argument 'exp' (for the experimental data array) or the number of +#' observational datasets available for validation (for the observational +#' array) determined as well by the user through the argument 'obs'.} +#' \item{The greatest number of members across all experiments (in the +#' experimental data array) or across all observational datasets (in the +#' observational data array).} +#' \item{The number of starting dates determined by the user through the +#' 'sdates' argument.} +#' \item{The greatest number of lead-times.} +#' \item{The number of latitudes of the selected zone.} +#' \item{The number of longitudes of the selected zone.} +#' } +#'Dimensions 5 and 6 are optional and their presence depends on the type of +#'the specified variable (global mean or 2-dimensional) and on the selected +#'output type (area averaged time series, latitude averaged time series, +#'longitude averaged time series or 2-dimensional time series).\cr +#'In the case of loading an area average the dimensions of the arrays will be +#'only the first 4.\cr\cr +#'Only a specified variable is loaded from each experiment at each starting +#'date. See parameter 'var'.\cr +#'Afterwards, observational data that matches every starting date and lead-time +#'of every experimental dataset is fetched in the file system (so, if two +#'predictions at two different start dates overlap, some observational values +#'will be loaded and kept in memory more than once).\cr +#'If no data is found in the file system for an experimental or observational +#'array point it is filled with an NA value.\cr\cr +#'If the specified output is 2-dimensional or latitude- or longitude-averaged +#'time series all the data is interpolated into a common grid. If the +#'specified output type is area averaged time series the data is averaged on +#'the individual grid of each dataset but can also be averaged after +#'interpolating into a common grid. See parameters 'grid' and 'method'.\cr +#'Once the two arrays are filled by calling this function, other functions in +#'the s2dverification package that receive as inputs data formatted in this +#'data structure can be executed (e.g: \code{Clim()} to compute climatologies, +#'\code{Ano()} to compute anomalies, ...).\cr\cr +#'Load() has many additional parameters to disable values and trim dimensions +#'of selected variable, even masks can be applied to 2-dimensional variables. +#'See parameters 'nmember', 'nmemberobs', 'nleadtime', 'leadtimemin', +#''leadtimemax', 'sampleperiod', 'lonmin', 'lonmax', 'latmin', 'latmax', +#''maskmod', 'maskobs', 'varmin', 'varmax'.\cr\cr +#'The parameters 'exp' and 'obs' can take various forms. The most direct form +#'is a list of lists, where each sub-list has the component 'path' associated +#'to a character string with a pattern of the path to the files of a dataset +#'to be loaded. These patterns can contain wildcards and tags that will be +#'replaced automatically by \code{Load()} with the specified starting dates, +#'member numbers, variable name, etc.\cr +#'See parameter 'exp' or 'obs' for details.\cr\cr +#'Only NetCDF files are supported. OPeNDAP URLs to NetCDF files are also +#'supported.\cr +#'\code{Load()} can load 2-dimensional or global mean variables in any of the +#'following formats: +#' \itemize{ +#' \item{experiments: +#' \itemize{ +#' \item{file per ensemble per starting date +#' (YYYY, MM and DD somewhere in the path)} +#' \item{file per member per starting date +#' (YYYY, MM, DD and MemberNumber somewhere in the path. Ensemble +#' experiments with different numbers of members can be loaded in +#' a single \code{Load()} call.)} +#' } +#' (YYYY, MM and DD specify the starting dates of the predictions) +#' } +#' \item{observations: +#' \itemize{ +#' \item{file per ensemble per month +#' (YYYY and MM somewhere in the path)} +#' \item{file per member per month +#' (YYYY, MM and MemberNumber somewhere in the path, obs with different +#' numbers of members supported)} +#' \item{file per dataset (No constraints in the path but the time axes +#' in the file have to be properly defined)} +#' } +#' (YYYY and MM correspond to the actual month data in the file) +#' } +#' } +#'In all the formats the data can be stored in a daily or monthly frequency, +#'or a multiple of these (see parameters 'storefreq' and 'sampleperiod').\cr +#'All the data files must contain the target variable defined over time and +#'potentially over members, latitude and longitude dimensions in any order, +#'time being the record dimension.\cr +#'In the case of a two-dimensional variable, the variables longitude and +#'latitude must be defined inside the data file too and must have the same +#'names as the dimension for longitudes and latitudes respectively.\cr +#'The names of these dimensions (and longitude and latitude variables) and the +#'name for the members dimension are expected to be 'longitude', 'latitude' +#'and 'ensemble' respectively. However, these names can be adjusted with the +#'parameter 'dimnames' or can be configured in the configuration file (read +#'below in parameters 'exp', 'obs' or see \code{?ConfigFileOpen} +#'for more information.\cr +#'All the data files are expected to have numeric values representable with +#'32 bits. Be aware when choosing the fill values or infinite values in the +#'datasets to load.\cr\cr +#'The Load() function returns a named list following a structure similar to +#'the used in the package 'downscaleR'.\cr +#'The components are the following: +#' \itemize{ +#' \item{'mod' is the array that contains the experimental data. It has the +#' attribute 'dimensions' associated to a vector of strings with the labels +#' of each dimension of the array, in order.} +#' \item{'obs' is the array that contains the observational data. It has +#' the attribute 'dimensions' associated to a vector of strings with the +#' labels of each dimension of the array, in order.} +#' \item{'obs' is the array that contains the observational data.} +#' \item{'lat' and 'lon' are the latitudes and longitudes of the grid into +#' which the data is interpolated (0 if the loaded variable is a global +#' mean or the output is an area average).\cr +#' Both have the attribute 'cdo_grid_des' associated with a character +#' string with the name of the common grid of the data, following the CDO +#' naming conventions for grids.\cr +#' The attribute 'projection' is kept for compatibility with 'downscaleR'. +#' } +#' \item{'Variable' has the following components: +#' \itemize{ +#' \item{'varName', with the short name of the loaded variable as +#' specified in the parameter 'var'.} +#' \item{'level', with information on the pressure level of the variable. +#' Is kept to NULL by now.} +#' } +#' And the following attributes: +#' \itemize{ +#' \item{'is_standard', kept for compatibility with 'downscaleR', +#' tells if a dataset has been homogenized to standards with +#' 'downscaleR' catalogs.} +#' \item{'units', a character string with the units of measure of the +#' variable, as found in the source files.} +#' \item{'longname', a character string with the long name of the +#' variable, as found in the source files.} +#' \item{'daily_agg_cellfun', 'monthly_agg_cellfun', 'verification_time', +#' kept for compatibility with 'downscaleR'.} +#' } +#' } +#' \item{'Datasets' has the following components: +#' \itemize{ +#' \item{'exp', a named list where the names are the identifying +#' character strings of each experiment in 'exp', each associated to a +#' list with the following components: +#' \itemize{ +#' \item{'members', a list with the names of the members of the +#' dataset.} +#' \item{'source', a path or URL to the source of the dataset.} +#' } +#' } +#' \item{'obs', similar to 'exp' but for observational datasets.} +#' } +#' } +#' \item{'Dates', with the follwing components: +#' \itemize{ +#' \item{'start', an array of dimensions (sdate, time) with the POSIX +#' initial date of each forecast time of each starting date.} +#' \item{'end', an array of dimensions (sdate, time) with the POSIX +#' final date of each forecast time of each starting date.} +#' } +#' } +#' \item{'InitializationDates', a vector of starting dates as specified in +#' 'sdates', in POSIX format.} +#' \item{'when', a time stamp of the date the \code{Load()} call to obtain +#' the data was issued.} +#' \item{'source_files', a vector of character strings with complete paths +#' to all the found files involved in the \code{Load()} call.} +#' \item{'not_found_files', a vector of character strings with complete +#' paths to not found files involved in the \code{Load()} call.} +#' } +#' +#'@param var Short name of the variable to load. It should coincide with the +#' variable name inside the data files.\cr +#' E.g.: \code{var = 'tos'}, \code{var = 'tas'}, \code{var = 'prlr'}.\cr +#' In some cases, though, the path to the files contains twice or more times +#' the short name of the variable but the actual name of the variable inside +#' the data files is different. In these cases it may be convenient to provide +#' \code{var} with the name that appears in the file paths (see details on +#' parameters \code{exp} and \code{obs}). +#'@param exp Parameter to specify which experimental datasets to load data +#' from.\cr +#' It can take two formats: a list of lists or a vector of character strings. +#' Each format will trigger a different mechanism of locating the requested +#' datasets.\cr +#' The first format is adequate when loading data you'll only load once or +#' occasionally. The second format is targeted to avoid providing repeatedly +#' the information on a certain dataset but is more complex to use.\cr\cr +#' IMPORTANT: Place first the experiment with the largest number of members +#' and, if possible, with the largest number of leadtimes. If not possible, +#' the arguments 'nmember' and/or 'nleadtime' should be filled to not miss +#' any member or leadtime.\cr +#' If 'exp' is not specified or set to NULL, observational data is loaded for +#' each start-date as far as 'leadtimemax'. If 'leadtimemax' is not provided, +#' \code{Load()} will retrieve data of a period of time as long as the time +#' period between the first specified start date and the current date.\cr\cr +#' List of lists:\cr +#' A list of lists where each sub-list contains information on the location +#' and format of the data files of the dataset to load.\cr +#' Each sub-list can have the following components: +#' \itemize{ +#' \item{'name': A character string to identify the dataset. Optional.} +#' \item{'path': A character string with the pattern of the path to the +#' files of the dataset. This pattern can be built up making use of some +#' special tags that \code{Load()} will replace with the appropriate +#' values to find the dataset files. The allowed tags are $START_DATE$, +#' $YEAR$, $MONTH$, $DAY$, $MEMBER_NUMBER$, $STORE_FREQ$, $VAR_NAME$, +#' $EXP_NAME$ (only for experimental datasets), $OBS_NAME$ (only for +#' observational datasets) and $SUFFIX$\cr +#' Example: /path/to/$EXP_NAME$/postprocessed/$VAR_NAME$/\cr +#' $VAR_NAME$_$START_DATE$.nc\cr +#' If 'path' is not specified and 'name' is specified, the dataset +#' information will be fetched with the same mechanism as when using +#' the vector of character strings (read below). +#' } +#' \item{'nc_var_name': Character string with the actual variable name +#' to look for inside the dataset files. Optional. Takes, by default, +#' the same value as the parameter 'var'. +#' } +#' \item{'suffix': Wildcard character string that can be used to build +#' the 'path' of the dataset. It can be accessed with the tag $SUFFIX$. +#' Optional. Takes '' by default. +#' } +#' \item{'var_min': Important: Character string. Minimum value beyond +#' which read values will be deactivated to NA. Optional. No deactivation +#' is performed by default. +#' } +#' \item{'var_max': Important: Character string. Maximum value beyond +#' which read values will be deactivated to NA. Optional. No deactivation +#' is performed by default. +#' } +#' } +#' The tag $START_DATES$ will be replaced with all the starting dates +#' specified in 'sdates'. $YEAR$, $MONTH$ and $DAY$ will take a value for each +#' iteration over 'sdates', simply these are the same as $START_DATE$ but +#' split in parts.\cr +#' $MEMBER_NUMBER$ will be replaced by a character string with each member +#' number, from 1 to the value specified in the parameter 'nmember' (in +#' experimental datasets) or in 'nmemberobs' (in observational datasets). It +#' will range from '01' to 'N' or '0N' if N < 10.\cr +#' $STORE_FREQ$ will take the value specified in the parameter 'storefreq' +#' ('monthly' or 'daily').\cr +#' $VAR_NAME$ will take the value specified in the parameter 'var'.\cr +#' $EXP_NAME$ will take the value specified in each component of the parameter +#' 'exp' in the sub-component 'name'.\cr +#' $OBS_NAME$ will take the value specified in each component of the parameter +#' 'obs' in the sub-component 'obs.\cr +#' $SUFFIX$ will take the value specified in each component of the parameters +#' 'exp' and 'obs' in the sub-component 'suffix'.\cr +#' Example: +#' \preformatted{ +#' list( +#' list( +#' name = 'experimentA', +#' path = file.path('/path/to/$DATASET_NAME$/$STORE_FREQ$', +#' '$VAR_NAME$$SUFFIX$', +#' '$VAR_NAME$_$START_DATE$.nc'), +#' nc_var_name = '$VAR_NAME$', +#' suffix = '_3hourly', +#' var_min = '-1e19', +#' var_max = '1e19' +#' ) +#' ) +#' } +#' This will make \code{Load()} look for, for instance, the following paths, +#' if 'sdates' is c('19901101', '19951101', '20001101'):\cr +#' /path/to/experimentA/monthly_mean/tas_3hourly/tas_19901101.nc\cr +#' /path/to/experimentA/monthly_mean/tas_3hourly/tas_19951101.nc\cr +#' /path/to/experimentA/monthly_mean/tas_3hourly/tas_20001101.nc\cr\cr +#' Vector of character strings: +#' To avoid specifying constantly the same information to load the same +#' datasets, a vector with only the names of the datasets to load can be +#' specified.\cr +#' \code{Load()} will then look for the information in a configuration file +#' whose path must be specified in the parameter 'configfile'.\cr +#' Check \code{?ConfigFileCreate}, \code{ConfigFileOpen}, +#' \code{ConfigEditEntry} & co. to learn how to create a new configuration +#' file and how to add the information there.\cr +#' Example: c('experimentA', 'experimentB') +#' +#'@param obs Argument with the same format as parameter 'exp'. See details on +#' parameter 'exp'.\cr +#' If 'obs' is not specified or set to NULL, no observational data is loaded.\cr +#'@param sdates Vector of starting dates of the experimental runs to be loaded +#' following the pattern 'YYYYMMDD'.\cr +#' This argument is mandatory.\cr +#' E.g. c('19601101', '19651101', '19701101') +#'@param nmember Vector with the numbers of members to load from the specified +#' experimental datasets in 'exp'.\cr +#' If not specified, the automatically detected number of members of the +#' first experimental dataset is detected and replied to all the experimental +#' datasets.\cr +#' If a single value is specified it is replied to all the experimental +#' datasets.\cr +#' Data for each member is fetched in the file system. If not found is +#' filled with NA values.\cr +#' An NA value in the 'nmember' list is interpreted as "fetch as many members +#' of each experimental dataset as the number of members of the first +#' experimental dataset".\cr +#' Note: It is recommended to specify the number of members of the first +#' experimental dataset if it is stored in file per member format because +#' there are known issues in the automatic detection of members if the path +#' to the dataset in the configuration file contains Shell Globbing wildcards +#' such as '*'.\cr +#' E.g., c(4, 9) +#'@param nmemberobs Vector with the numbers of members to load from the +#' specified observational datasets in 'obs'.\cr +#' If not specified, the automatically detected number of members of the +#' first observational dataset is detected and replied to all the +#' observational datasets.\cr +#' If a single value is specified it is replied to all the observational +#' datasets.\cr +#' Data for each member is fetched in the file system. If not found is +#' filled with NA values.\cr +#' An NA value in the 'nmemberobs' list is interpreted as "fetch as many +#' members of each observational dataset as the number of members of the +#' first observational dataset".\cr +#' Note: It is recommended to specify the number of members of the first +#' observational dataset if it is stored in file per member format because +#' there are known issues in the automatic detection of members if the path +#' to the dataset in the configuration file contains Shell Globbing wildcards +#' such as '*'.\cr +#' E.g., c(1, 5) +#'@param nleadtime Deprecated. See parameter 'leadtimemax'. +#'@param leadtimemin Only lead-times higher or equal to 'leadtimemin' are +#' loaded. Takes by default value 1. +#'@param leadtimemax Only lead-times lower or equal to 'leadtimemax' are loaded. +#' Takes by default the number of lead-times of the first experimental +#' dataset in 'exp'.\cr +#' If 'exp' is NULL this argument won't have any effect +#' (see \code{?Load} description). +#'@param storefreq Frequency at which the data to be loaded is stored in the +#' file system. Can take values 'monthly' or 'daily'.\cr +#' By default it takes 'monthly'.\cr +#' Note: Data stored in other frequencies with a period which is divisible by +#' a month can be loaded with a proper use of 'storefreq' and 'sampleperiod' +#' parameters. It can also be loaded if the period is divisible by a day and +#' the observational datasets are stored in a file per dataset format or +#' 'obs' is empty. +#'@param sampleperiod To load only a subset between 'leadtimemin' and +#' 'leadtimemax' with the period of subsampling 'sampleperiod'.\cr +#' Takes by default value 1 (all lead-times are loaded).\cr +#' See 'storefreq' for more information. +#'@param lonmin If a 2-dimensional variable is loaded, values at longitudes +#' lower than 'lonmin' aren't loaded.\cr +#' Must take a value in the range [-360, 360] (if negative longitudes are +#' found in the data files these are translated to this range).\cr +#' It is set to 0 if not specified.\cr +#' If 'lonmin' > 'lonmax', data across Greenwich is loaded. +#'@param lonmax If a 2-dimensional variable is loaded, values at longitudes +#' higher than 'lonmax' aren't loaded.\cr +#' Must take a value in the range [-360, 360] (if negative longitudes are +#' found in the data files these are translated to this range).\cr +#' It is set to 360 if not specified.\cr +#' If 'lonmin' > 'lonmax', data across Greenwich is loaded. +#'@param latmin If a 2-dimensional variable is loaded, values at latitudes +#' lower than 'latmin' aren't loaded.\cr +#' Must take a value in the range [-90, 90].\cr +#' It is set to -90 if not specified. +#'@param latmax If a 2-dimensional variable is loaded, values at latitudes +#' higher than 'latmax' aren't loaded.\cr +#' Must take a value in the range [-90, 90].\cr +#' It is set to 90 if not specified. +#'@param output This parameter determines the format in which the data is +#' arranged in the output arrays.\cr +#' Can take values 'areave', 'lon', 'lat', 'lonlat'.\cr +#' \itemize{ +#' \item{'areave': Time series of area-averaged variables over the specified domain.} +#' \item{'lon': Time series of meridional averages as a function of longitudes.} +#' \item{'lat': Time series of zonal averages as a function of latitudes.} +#' \item{'lonlat': Time series of 2d fields.} +#' } +#' Takes by default the value 'areave'. If the variable specified in 'var' is +#' a global mean, this parameter is forced to 'areave'.\cr +#' All the loaded data is interpolated into the grid of the first experimental +#' dataset except if 'areave' is selected. In that case the area averages are +#' computed on each dataset original grid. A common grid different than the +#' first experiment's can be specified through the parameter 'grid'. If 'grid' +#' is specified when selecting 'areave' output type, all the loaded data is +#' interpolated into the specified grid before calculating the area averages. +#'@param method This parameter determines the interpolation method to be used +#' when regridding data (see 'output'). Can take values 'bilinear', 'bicubic', +#' 'conservative', 'distance-weighted'.\cr +#' See \code{remapcells} for advanced adjustments.\cr +#' Takes by default the value 'conservative'. +#'@param grid A common grid can be specified through the parameter 'grid' when +#' loading 2-dimensional data. Data is then interpolated onto this grid +#' whichever 'output' type is specified. If the selected output type is +#' 'areave' and a 'grid' is specified, the area averages are calculated after +#' interpolating to the specified grid.\cr +#' If not specified and the selected output type is 'lon', 'lat' or 'lonlat', +#' this parameter takes as default value the grid of the first experimental +#' dataset, which is read automatically from the source files.\cr +#' The grid must be supported by 'cdo' tools. Now only supported: rNXxNY +#' or tTRgrid.\cr +#' Both rNXxNY and tRESgrid yield rectangular regular grids. rNXxNY yields +#' grids that are evenly spaced in longitudes and latitudes (in degrees). +#' tRESgrid refers to a grid generated with series of spherical harmonics +#' truncated at the RESth harmonic. However these spectral grids are usually +#' associated to a gaussian grid, the latitudes of which are spaced with a +#' Gaussian quadrature (not evenly spaced in degrees). The pattern tRESgrid +#' will yield a gaussian grid.\cr +#' E.g., 'r96x72' +#' Advanced: If the output type is 'lon', 'lat' or 'lonlat' and no common +#' grid is specified, the grid of the first experimental or observational +#' dataset is detected and all data is then interpolated onto this grid. +#' If the first experimental or observational dataset's data is found shifted +#' along the longitudes (i.e., there's no value at the longitude 0 but at a +#' longitude close to it), the data is re-interpolated to suppress the shift. +#' This has to be done in order to make sure all the data from all the +#' datasets is properly aligned along longitudes, as there's no option so far +#' in \code{Load} to specify grids starting at longitudes other than 0. +#' This issue doesn't affect when loading in 'areave' mode without a common +#' grid, the data is not re-interpolated in that case. +#'@param maskmod List of masks to be applied to the data of each experimental +#' dataset respectively, if a 2-dimensional variable is specified in 'var'.\cr +#' Each mask can be defined in 2 formats:\cr +#' a) a matrix with dimensions c(longitudes, latitudes).\cr +#' b) a list with the components 'path' and, optionally, 'nc_var_name'.\cr +#' In the format a), the matrix must have the same size as the common grid +#' or with the same size as the grid of the corresponding experimental dataset +#' if 'areave' output type is specified and no common 'grid' is specified.\cr +#' In the format b), the component 'path' must be a character string with the +#' path to a NetCDF mask file, also in the common grid or in the grid of the +#' corresponding dataset if 'areave' output type is specified and no common +#' 'grid' is specified. If the mask file contains only a single variable, +#' there's no need to specify the component 'nc_var_name'. Otherwise it must +#' be a character string with the name of the variable inside the mask file +#' that contains the mask values. This variable must be defined only over 2 +#' dimensions with length greater or equal to 1.\cr +#' Whichever the mask format, a value of 1 at a point of the mask keeps the +#' original value at that point whereas a value of 0 disables it (replaces +#' by a NA value).\cr +#' By default all values are kept (all ones).\cr +#' The longitudes and latitudes in the matrix must be in the same order as in +#' the common grid or as in the original grid of the corresponding dataset +#' when loading in 'areave' mode. You can find out the order of the longitudes +#' and latitudes of a file with 'cdo griddes'.\cr +#' Note that in a common CDO grid defined with the patterns 'tgrid' or +#' 'rx' the latitudes and latitudes are ordered, by definition, from +#' -90 to 90 and from 0 to 360, respectively.\cr +#' If you are loading maps ('lonlat', 'lon' or 'lat' output types) all the +#' data will be interpolated onto the common 'grid'. If you want to specify +#' a mask, you will have to provide it already interpolated onto the common +#' grid (you may use 'cdo' libraries for this purpose). It is not usual to +#' apply different masks on experimental datasets on the same grid, so all +#' the experiment masks are expected to be the same.\cr +#' Warning: When loading maps, any masks defined for the observational data +#' will be ignored to make sure the same mask is applied to the experimental +#' and observational data.\cr +#' Warning: list() compulsory even if loading 1 experimental dataset only!\cr +#' E.g., list(array(1, dim = c(num_lons, num_lats))) +#'@param maskobs See help on parameter 'maskmod'. +#'@param configfile Path to the s2dverification configuration file from which +#' to retrieve information on location in file system (and other) of datasets.\cr +#' If not specified, the configuration file used at BSC-ES will be used +#' (it is included in the package).\cr +#' Check the BSC's configuration file or a template of configuration file in +#' the folder 'inst/config' in the package.\cr +#' Check further information on the configuration file mechanism in +#' \code{ConfigFileOpen()}. +#'@param varmin Loaded experimental and observational data values smaller +#' than 'varmin' will be disabled (replaced by NA values).\cr +#' By default no deactivation is performed. +#'@param varmax Loaded experimental and observational data values greater +#' than 'varmax' will be disabled (replaced by NA values).\cr +#' By default no deactivation is performed. +#'@param silent Parameter to show (FALSE) or hide (TRUE) information messages.\cr +#' Warnings will be displayed even if 'silent' is set to TRUE.\cr +#' Takes by default the value 'FALSE'. +#'@param nprocs Number of parallel processes created to perform the fetch +#' and computation of data.\cr +#' These processes will use shared memory in the processor in which Load() +#' is launched.\cr +#' By default the number of logical cores in the machine will be detected +#' and as many processes as logical cores there are will be created.\cr +#' A value of 1 won't create parallel processes.\cr +#' When running in multiple processes, if an error occurs in any of the +#' processes, a crash message appears in the R session of the original +#' process but no detail is given about the error. A value of 1 will display +#' all error messages in the original and only R session.\cr +#' Note: the parallel process create other blocking processes each time they +#' need to compute an interpolation via 'cdo'. +#'@param dimnames Named list where the name of each element is a generic +#' name of the expected dimensions inside the NetCDF files. These generic +#' names are 'lon', 'lat' and 'member'. 'time' is not needed because it's +#' detected automatically by discard.\cr +#' The value associated to each name is the actual dimension name in the +#' NetCDF file.\cr +#' The variables in the file that contain the longitudes and latitudes of +#' the data (if the data is a 2-dimensional variable) must have the same +#' name as the longitude and latitude dimensions.\cr +#' By default, these names are 'longitude', 'latitude' and 'ensemble. If any +#' of those is defined in the 'dimnames' parameter, it takes priority and +#' overwrites the default value. +#' E.g., list(lon = 'x', lat = 'y') +#' In that example, the dimension 'member' will take the default value 'ensemble'. +#'@param remapcells When loading a 2-dimensional variable, spatial subsets can +#' be requested via \code{lonmin}, \code{lonmax}, \code{latmin} and +#' \code{latmax}. When \code{Load()} obtains the subset it is then +#' interpolated if needed with the method specified in \code{method}.\cr +#' The result of this interpolation can vary if the values surrounding the +#' spatial subset are not present. To better control this process, the width +#' in number of grid cells of the surrounding area to be taken into account +#' can be specified with \code{remapcells}. A value of 0 will take into +#' account no additional cells but will generate less traffic between the +#' storage and the R processes that load data.\cr +#' A value beyond the limits in the data files will be automatically runcated +#' to the actual limit.\cr +#' The default value is 2. +#'@param path_glob_permissive In some cases, when specifying a path pattern +#' (either in the parameters 'exp'/'obs' or in a configuration file) one can +#' specify path patterns that contain shell globbing expressions. Too much +#' freedom in putting globbing expressions in the path patterns can be +#' dangerous and make \code{Load()} find a file in the file system for a +#' start date for a dataset that really does not belong to that dataset. +#' For example, if the file system contains two directories for two different +#' experiments that share a part of their path and the path pattern contains +#' globbing expressions: +#' /experiments/model1/expA/monthly_mean/tos/tos_19901101.nc +#' /experiments/model2/expA/monthly_mean/tos/tos_19951101.nc +#' And the path pattern is used as in the example right below to load data of +#' only the experiment 'expA' of the model 'model1' for the starting dates +#' '19901101' and '19951101', \code{Load()} will undesiredly yield data for +#' both starting dates, even if in fact there is data only for the +#' first one:\cr +#' \code{ +#' expA <- list(path = file.path('/experiments/*/expA/monthly_mean/$VAR_NAME$', +#' '$VAR_NAME$_$START_DATE$.nc') +#' data <- Load('tos', list(expA), NULL, c('19901101', '19951101')) +#' } +#' To avoid these situations, the parameter \code{path_glob_permissive} is +#' set by default to \code{'partial'}, which forces \code{Load()} to replace +#' all the globbing expressions of a path pattern of a data set by fixed +#' values taken from the path of the first found file for each data set, up +#' to the folder right before the final files (globbing expressions in the +#' file name will not be replaced, only those in the path to the file). +#' Replacement of globbing expressions in the file name can also be triggered +#' by setting \code{path_glob_permissive} to \code{FALSE} or \code{'no'}. If +#' needed to keep all globbing expressions, \code{path_glob_permissive} can +#' be set to \code{TRUE} or \code{'yes'}. +#' +#'@details +#'The two output matrices have between 2 and 6 dimensions:\cr +#' \enumerate{ +#' \item{Number of experimental/observational datasets.} +#' \item{Number of members.} +#' \item{Number of startdates.} +#' \item{Number of leadtimes.} +#' \item{Number of latitudes (optional).} +#' \item{Number of longitudes (optional).} +#' } +#'but the two matrices have the same number of dimensions and only the first +#'two dimensions can have different lengths depending on the input arguments. +#'For a detailed explanation of the process, read the documentation attached +#'to the package or check the comments in the code. +#' +#'@return +#'\code{Load()} returns a named list following a structure similar to the +#'used in the package 'downscaleR'.\cr +#'The components are the following: +#' \itemize{ +#' \item{ +#' 'mod' is the array that contains the experimental data. It has the +#' attribute 'dimensions' associated to a vector of strings with the +#' labels of each dimension of the array, in order. The order of the +#' latitudes is always forced to be from 90 to -90 whereas the order of +#' the longitudes is kept as in the original files (if possible). The +#' longitude values provided in \code{lon} lower than 0 are added 360 +#' (but still kept in the original order). In some cases, however, if +#' multiple data sets are loaded in longitude-latitude mode, the +#' longitudes (and also the data arrays in \code{mod} and \code{obs}) are +#' re-ordered afterwards by \code{Load()} to range from 0 to 360; a +#' warning is given in such cases. The longitude and latitude of the +#' center of the grid cell that corresponds to the value [j, i] in 'mod' +#' (along the dimensions latitude and longitude, respectively) can be +#' found in the outputs \code{lon}[i] and \code{lat}[j] +#' } +#' \item{'obs' is the array that contains the observational data. The +#' same documentation of parameter 'mod' applies to this parameter.} +#' \item{'lat' and 'lon' are the latitudes and longitudes of the centers of +#' the cells of the grid the data is interpolated into (0 if the loaded +#' variable is a global mean or the output is an area average).\cr +#' Both have the attribute 'cdo_grid_des' associated with a character +#' string with the name of the common grid of the data, following the CDO +#' naming conventions for grids.\cr +#' 'lon' has the attributes 'first_lon' and 'last_lon', with the first +#' and last longitude values found in the region defined by 'lonmin' and +#' 'lonmax'. 'lat' has also the equivalent attributes 'first_lat' and +#' 'last_lat'.\cr +#' 'lon' has also the attribute 'data_across_gw' which tells whether the +#' requested region via 'lonmin', 'lonmax', 'latmin', 'latmax' goes across +#' the Greenwich meridian. As explained in the documentation of the +#' parameter 'mod', the loaded data array is kept in the same order as in +#' the original files when possible: this means that, in some cases, even +#' if the data goes across the Greenwich, the data array may not go +#' across the Greenwich. The attribute 'array_across_gw' tells whether +#' the array actually goes across the Greenwich. E.g: The longitudes in +#' the data files are defined to be from 0 to 360. The requested +#' longitudes are from -80 to 40. The original order is kept, hence the +#' longitudes in the array will be ordered as follows: +#' 0, ..., 40, 280, ..., 360. In that case, 'data_across_gw' will be TRUE +#' and 'array_across_gw' will be FALSE.\cr +#' The attribute 'projection' is kept for compatibility with 'downscaleR'. +#' } +#' \item{'Variable' has the following components: +#' \itemize{ +#' \item{'varName', with the short name of the loaded variable as +#' specified in the parameter 'var'. +#' } +#' \item{'level', with information on the pressure level of the +#' variable. Is kept to NULL by now. +#' } +#' } +#' And the following attributes: +#' \itemize{ +#' \item{'is_standard', kept for compatibility with 'downscaleR', +#' tells if a dataset has been homogenized to standards with +#' 'downscaleR' catalogs. +#' } +#' \item{'units', a character string with the units of measure of the +#' variable, as found in the source files. +#' } +#' \item{'longname', a character string with the long name of the +#' variable, as found in the source files. +#' } +#' \item{'daily_agg_cellfun', 'monthly_agg_cellfun', +#' 'verification_time', kept for compatibility with 'downscaleR'. +#' } +#' } +#' } +#' \item{'Datasets' has the following components: +#' \itemize{ +#' \item{'exp', a named list where the names are the identifying +#' character strings of each experiment in 'exp', each associated to +#' a list with the following components: +#' \itemize{ +#' \item{'members', a list with the names of the members of the dataset.} +#' \item{'source', a path or URL to the source of the dataset.} +#' } +#' } +#' \item{'obs', similar to 'exp' but for observational datasets.} +#' } +#' } +#' \item{'Dates', with the follwing components: +#' \itemize{ +#' \item{'start', an array of dimensions (sdate, time) with the POSIX +#' initial date of each forecast time of each starting date. +#' } +#' \item{'end', an array of dimensions (sdate, time) with the POSIX +#' final date of each forecast time of each starting date. +#' } +#' } +#' } +#' \item{'InitializationDates', a vector of starting dates as specified in +#' 'sdates', in POSIX format. +#' } +#' \item{'when', a time stamp of the date the \code{Load()} call to obtain +#' the data was issued. +#' } +#' \item{'source_files', a vector of character strings with complete paths +#' to all the found files involved in the \code{Load()} call. +#' } +#' \item{'not_found_files', a vector of character strings with complete +#' paths to not found files involved in the \code{Load()} call. +#' } +#' } +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@bsc.es}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Formatting to CRAN\cr +#'1.2 - 2015-02 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Generalisation + parallelisation\cr +#'1.3 - 2015-07 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Improvements related to configuration file mechanism\cr +#'1.4 - 2016-01 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Added subsetting capabilities +#'@examples +#'# Let's assume we want to perform verification with data of a variable +#'# called 'tos' from a model called 'model' and observed data coming from +#'# an observational dataset called 'observation'. +#'# +#'# The model was run in the context of an experiment named 'experiment'. +#'# It simulated from 1st November in 1985, 1990, 1995, 2000 and 2005 for a +#'# period of 5 years time from each starting date. 5 different sets of +#'# initial conditions were used so an ensemble of 5 members was generated +#'# for each starting date. +#'# The model generated values for the variables 'tos' and 'tas' in a +#'# 3-hourly frequency but, after some initial post-processing, it was +#'# averaged over every month. +#'# The resulting monthly average series were stored in a file for each +#'# starting date for each variable with the data of the 5 ensemble members. +#'# The resulting directory tree was the following: +#'# model +#'# |--> experiment +#'# |--> monthly_mean +#'# |--> tos_3hourly +#'# | |--> tos_19851101.nc +#'# | |--> tos_19901101.nc +#'# | . +#'# | . +#'# | |--> tos_20051101.nc +#'# |--> tas_3hourly +#'# |--> tas_19851101.nc +#'# |--> tas_19901101.nc +#'# . +#'# . +#'# |--> tas_20051101.nc +#'# +#'# The observation recorded values of 'tos' and 'tas' at each day of the +#'# month over that period but was also averaged over months and stored in +#'# a file per month. The directory tree was the following: +#'# observation +#'# |--> monthly_mean +#'# |--> tos +#'# | |--> tos_198511.nc +#'# | |--> tos_198512.nc +#'# | |--> tos_198601.nc +#'# | . +#'# | . +#'# | |--> tos_201010.nc +#'# |--> tas +#'# |--> tas_198511.nc +#'# |--> tas_198512.nc +#'# |--> tas_198601.nc +#'# . +#'# . +#'# |--> tas_201010.nc +#'# +#'# The model data is stored in a file-per-startdate fashion and the +#'# observational data is stored in a file-per-month, and both are stored in +#'# a monthly frequency. The file format is NetCDF. +#'# Hence all the data is supported by Load() (see details and other supported +#'# conventions in ?Load) but first we need to configure it properly. +#'# +#'# These data files are included in the package (in the 'sample_data' folder), +#'# only for the variable 'tos'. They have been interpolated to a very low +#'# resolution grid so as to make it on CRAN. +#'# The original grid names (following CDO conventions) for experimental and +#'# observational data were 't106grid' and 'r180x89' respectively. The final +#'# resolutions are 'r20x10' and 'r16x8' respectively. +#'# The experimental data comes from the decadal climate prediction experiment +#'# run at IC3 in the context of the CMIP5 project. Its name within IC3 local +#'# database is 'i00k'. +#'# The observational dataset used for verification is the 'ERSST' +#'# observational dataset. +#'# +#'# The next two examples are equivalent and show how to load the variable +#'# 'tos' from these sample datasets, the first providing lists of lists to +#'# the parameters 'exp' and 'obs' (see documentation on these parameters) and +#'# the second providing vectors of character strings, hence using a +#'# configuration file. +#'# +#'# The code is not run because it dispatches system calls to 'cdo' which is +#'# not allowed in the examples as per CRAN policies. You can run it on your +#'# system though. +#'# Instead, the code in 'dontshow' is run, which loads the equivalent +#'# already processed data in R. +#'# +#'# Example 1: Providing lists of lists to 'exp' and 'obs': +#'# +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'exp <- list( +#' name = 'experiment', +#' path = file.path(data_path, 'model/$EXP_NAME$/monthly_mean', +#' '$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATES$.nc') +#' ) +#'obs <- list( +#' name = 'observation', +#' path = file.path(data_path, 'observation/$OBS_NAME$/monthly_mean', +#' '$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') +#' ) +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(exp), list(obs), startDates, +#' output = 'areave', latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'# +#'# Example 2: Providing vectors of character strings to 'exp' and 'obs' +#'# and using a configuration file. +#'# +#'# The configuration file 'sample.conf' that we will create in the example +#'# has the proper entries to load these (see ?LoadConfigFile for details on +#'# writing a configuration file). +#'# +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' output = 'areave', latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#'# +#'# Example 2: providing character strings in 'exp' and 'obs', and providing +#'# a configuration file. +#'# The configuration file 'sample.conf' that we will create in the example +#'# has the proper entries to load these (see ?LoadConfigFile for details on +#'# writing a configuration file). +#'# +#'configfile <- paste0(tempdir(), '/sample.conf') +#'ConfigFileCreate(configfile, confirm = FALSE) +#'c <- ConfigFileOpen(configfile) +#'c <- ConfigEditDefinition(c, 'DEFAULT_VAR_MIN', '-1e19', confirm = FALSE) +#'c <- ConfigEditDefinition(c, 'DEFAULT_VAR_MAX', '1e19', confirm = FALSE) +#'data_path <- system.file('sample_data', package = 's2dverification') +#'exp_data_path <- paste0(data_path, '/model/$EXP_NAME$/') +#'obs_data_path <- paste0(data_path, '/$OBS_NAME$/') +#'c <- ConfigAddEntry(c, 'experiments', dataset_name = 'experiment', +#' var_name = 'tos', main_path = exp_data_path, +#' file_path = '$STORE_FREQ$_mean/$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATE$.nc') +#'c <- ConfigAddEntry(c, 'observations', dataset_name = 'observation', +#' var_name = 'tos', main_path = obs_data_path, +#' file_path = '$STORE_FREQ$_mean/$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') +#'ConfigFileSave(c, configfile, confirm = FALSE) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', c('experiment'), c('observation'), startDates, +#' output = 'areave', latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40, configfile = configfile) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' output = 'areave', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'@import parallel bigmemory methods +#'@importFrom stats ts window na.omit +#'@export Load <- function(var, exp = NULL, obs = NULL, sdates, nmember = NULL, nmemberobs = NULL, nleadtime = NULL, leadtimemin = 1, leadtimemax = NULL, storefreq = 'monthly', sampleperiod = 1, diff --git a/R/Mean1Dim.R b/R/Mean1Dim.R index 300b9de42d38402f6f8d3a48171bce198d3a4851..d8abbfa9245b7ceb11dce0a5db029ce5b7c91532 100644 --- a/R/Mean1Dim.R +++ b/R/Mean1Dim.R @@ -1,3 +1,27 @@ +#'Averages An Array Along A Dimension +#' +#'Averages the array along the posdim dimension along the user specified +#'dimension. The user can specify a subset of the dimension to take the mean +#'along. +#' +#'@param var Matrix to average. +#'@param posdim Dimension to average along. +#'@param narm Ignore NA (TRUE) values or not (FALSE). +#'@param limits Limits to average between. Default is to take the mean along +#' the entire dimension. +#' +#'@return Array with one dimension less than the input array, containing +#' the average along the posdim dimension. +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2011-04 (V. Guemas, \email{virginie.guemas@@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to R CRAN +#'@examples +#'a <- array(rnorm(24), dim = c(2, 3, 4)) +#'print(a) +#'print(Mean1Dim(a, 2)) +#'@export Mean1Dim <- function(var, posdim, narm = TRUE, limits = NULL) { if (is.null(limits)) { limits <- c(1, dim(var)[posdim]) diff --git a/R/MeanListDim.R b/R/MeanListDim.R index 2a49e00288149e9412b9124f3327e2ccced22761..2b9a25372e280b7ffb5b7b77483d5c46367835c9 100644 --- a/R/MeanListDim.R +++ b/R/MeanListDim.R @@ -1,3 +1,25 @@ +#'Averages An Array Along Multiple Dimensions +#' +#'Averages an array along a set of dimensions given by the argument dims. +#' +#'@param var Input array. +#'@param dims List of dimensions to average along. +#'@param narm Ignore NA (TRUE) values or not (FALSE). +#' +#'@return The averaged array, with the dimensions specified in \code{dims} +#' removed. +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2011-04 (V. Guemas, \email{vguemas@@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to R CRAN\cr +#'1.1 - 2015-03 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Improved memory usage +#'@examples +#'a <- array(rnorm(24), dim = c(2, 3, 4)) +#'print(a) +#'print(Mean1Dim(a, 2)) +#'print(MeanListDim(a, c(2, 3))) +#'@export MeanListDim <- function(var, dims, narm = TRUE) { apply(var, setdiff(c(1:length(dim(var))), dims), mean, na.rm = narm) } diff --git a/R/NAO.R b/R/NAO.R index faccb821cd73c9a7dcf61c8b3793ae3e982d45ce..c0d7c94d10ec2bb96d7109508081cb0d777917f2 100644 --- a/R/NAO.R +++ b/R/NAO.R @@ -1,3 +1,120 @@ +#'Computes the North Atlantic Oscillation (NAO) Index +#' +#'Compute the North Atlantic Oscillation (NAO) index based on the leading EOF +#'of the sea level pressure (SLP) anomalies over the north Atlantic region +#'(20N-80N, 80W-40E). The PCs are obtained by projecting the forecast and +#'observed anomalies onto the observed EOF pattern (Pobs) or the forecast +#'anomalies onto the EOF pattern of the other years of the forecast (Pmod). +#'By default (ftime_average = 2:4) NAO() computes the NAO index for 1-month +#'lead seasonal forecasts that can be plotted with BoxPlot(). Returns +#'cross-validated PCs of the NAO index for forecast (ano_exp) and observations +#'(ano_obs) based on the leading EOF pattern. +#' +#'@param ano_exp Array of North Atlantic SLP (20N-80N, 80W-40E) forecast +#' anomalies from \code{Ano()} or \code{Ano_CrossValid()} with dimensions +#' (n. of experimental data sets, n. of ensemble members, n. of start dates, +#' n. of forecast time steps, n. of latitudes, n. of longitudes). If only +#' NAO of observational data needs to be computed, this parameter can be left +#' to NULL (default). +#'@param ano_obs Array of North Atlantic SLP (20N-80N, 80W-40E) observed +#' anomalies from \code{Ano()} or \code{Ano_CrossValid()} with dimensions +#' (n. of observational data sets, n. of obs. ensemble members, +#' n. of start dates, n. of forecast time steps, n. of latitudes, +#' n. of longitudes). If only NAO of experimental data needs to be computed, +#' this parameter can be left to NULL (default). +#'@param lon Vector with the longitudes of \code{ano_exp} and \code{ano_obs}. +#'@param lat Vector with the latitudes of \code{ano_exp} and \code{ano_obs}. +#'@param ftime_average A vector with the forecast time steps to average across +#' defining the target period. Takes by default 2:4, i.e. from 2nd to 4th +#' forecast time steps. +#'@param obsproj \code{obsproj = TRUE} will compute the NAO index by +#' projecting the forecast anomalies onto the leading EOF of observational +#' reference.\cr +#' \code{obsproj = FALSE} will compute the NAO by first computing the leading +#' EOF of the forecast anomalies (in cross-validation mode, i.e. leaving the +#' year you are evaluating out), and then projecting forecast anomalies onto +#' this EOF. +#' +#'@return +#'\item{NAO_exp}{ +#' Array of forecast NAO index in verification format (ensemble members, +#' start dates). +#' } +#'\item{NAO_obs}{ +#' Array of observed NAO index in verification format (1, number of start +#' dates). +#'} +#'\item{EOFs_obs}{ +#' EOFs of the observational references. +#'} +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2013-08 (F. Lienert, \email{flienert@ic3.cat}) - Original code\cr +#'0.2 - 2014-03 (V. Guemas, \email{virginie.guemas@bsc.es}) - Removing the +#' rotation\cr +#'0.3 - 2014-05 (L. Batte, \email{lauriane.batte@ic3.cat}) - Changes to +#' simplify function and add Pobs and Pmod options for NAO projection +#' calculations\cr +#'0.4 - 2015-03 (L. Batte, \email{lauriane.batte@ic3.cat}) - Polarity +#' check and correction is wrong. Switched to have a negative NAO index when the +#' anomaly pattern corresponds to NAO-. +#'1.0 - 2016-03 (N. Manubens, \email{nicolau.manubens@bsc.es}) - +#' Formatted to CRAN +#'@references +#'Doblas-Reyes, F.J., Pavan, V. and Stephenson, D. (2003). The skill of +#' multi-model seasonal forecasts of the wintertime North Atlantic Oscillation. +#' Climate Dynamics, 21, 501-514. DOI: 10.1007/s00382-003-0350-4 +#' +#'@examples +#'# See examples on Load() to understand the first lines in this example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' leadtimemin = 1, leadtimemax = 4, output = 'lonlat', +#' latmin = 20, latmax = 90, lonmin = -80, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' leadtimemin = 1, +#' leadtimemax = 4, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#'# No example data is available over NAO region, so in this example we will +#'# tweak the available data. In a real use case, one can Load() the data over +#'# NAO region directly. +#'sampleData$lon[] <- c(40, 280, 340) +#'attr(sampleData$lon, 'first_lon') <- 280 +#'attr(sampleData$lon, 'last_lon') <- 40 +#'attr(sampleData$lon, 'data_across_gw') <- TRUE +#'sampleData$lat[] <- c(20, 80) +#'attr(sampleData$lat, 'first_lat') <- 20 +#'attr(sampleData$lat, 'last_lat') <- 80 +#' } +#' +#'# Now ready to compute the EOFs and project on, for example, the first +#'# variability mode. +#'ano <- Ano_CrossValid(sampleData$mod, sampleData$obs) +#'# Note that computing the NAO over the region for which there is available +#'# example data is not the full NAO area: NAO() will raise a warning. +#'nao <- NAO(ano$ano_exp, ano$ano_obs, sampleData$lon, sampleData$lat) +#'# Finally plot the NAO index +#'PlotBoxWhisker(nao$NAO_exp, nao$NAO_obs, "NAO index, DJF", "NAO index (PC1) TOS", +#' monini = 12, yearini = 1985, freq = 1, "Exp. A", "Obs. X") +#' +#'@export NAO <- function(ano_exp = NULL, ano_obs = NULL, lon, lat, ftime_average = 2:4, obsproj = TRUE) { # Checking ano_exp if (!is.null(ano_exp)) { diff --git a/R/Plot2VarsVsLTime.R b/R/Plot2VarsVsLTime.R index b23a25ad161ab0924b07794e330adb98c5f35b9c..c5d5abcf88420044f33e426e834889365df23bda 100644 --- a/R/Plot2VarsVsLTime.R +++ b/R/Plot2VarsVsLTime.R @@ -1,3 +1,89 @@ +#'Plot Two Scores With Confidence Intervals In A Common Plot +#' +#'Plots two input variables having the same dimensions in a common plot.\cr +#'One plot for all experiments.\cr +#'Input variables should have dimensions (nexp/nmod, nltime). +#' +#'@param var1 Matrix of dimensions (nexp/nmod, nltime). +#'@param var2 Matrix of dimensions (nexp/nmod, nltime). +#'@param toptitle Main title, optional. +#'@param ytitle Title of Y-axis, optional. +#'@param monini Starting month between 1 and 12. Default = 1. +#'@param freq 1 = yearly, 12 = monthly, 4 = seasonal, ... Default = 12. +#'@param nticks Number of ticks and labels on the x-axis, optional. +#'@param limits c(lower limit, upper limit): limits of the Y-axis, optional. +#'@param listexp List of experiment names, up to three, optional. +#'@param listvars List of names of input variables, optional. +#'@param biglab TRUE/FALSE for presentation/paper plot. Default = FALSE. +#'@param hlines c(a, b, ...) Add horizontal black lines at Y-positions a, b, +#' ...\cr +#' Default: NULL. +#'@param leg TRUE/FALSE if legend should be added or not to the plot. +#' Default = TRUE. +#'@param siglev TRUE/FALSE if significance level should replace confidence +#' interval.\cr +#' Default = FALSE. +#'@param sizetit Multiplicative factor to change title size, optional. +#'@param show_conf TRUE/FALSE to show/not confidence intervals for input +#' variables. +#'@param fileout Name of output file. Extensions allowed: eps/ps, jpeg, png, +#' pdf, bmp and tiff. \cr +#' Default = 'output_plot2varsvsltime.eps' +#'@param width File width, in the units specified in the parameter size_units +#' (inches by default). Takes 8 by default. +#'@param height File height, in the units specified in the parameter +#' size_units (inches by default). Takes 5 by default. +#'@param size_units Units of the size of the device (file or window) to plot +#' in. Inches ('in') by default. See ?Devices and the creator function of the +#' corresponding device. +#'@param res Resolution of the device (file or window) to plot in. See +#' ?Devices and the creator function of the corresponding device. +#'@param ... Arguments to be passed to the method. Only accepts the following +#' graphical parameters:\cr +#' adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt +#' csi cxy err family fg fig font font.axis font.lab font.main font.sub lend +#' lheight ljoin lmitre mar mex mfcol mfrow mfg mkh oma omd omi page pch plt +#' smo srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog \cr +#' For more information about the parameters see `par`. +#' +#'@details +#'Examples of input:\cr +#'------------------\cr\cr +#'RMSE error for a number of experiments and along lead-time: (nexp, nltime) +#' +#'@keywords dynamic +#'@author History:\cr +#'1.0 - 2013-03 (I. Andreu-Burillo, \email{isabel.andreu-burillo@@ic3.cat}) +#' - Original code +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'ano_exp <- Ano(sampleData$mod, clim$clim_exp) +#'ano_obs <- Ano(sampleData$obs, clim$clim_obs) +#'runmean_months <- 12 +#'dim_to_smooth <- 4 # Smooth along lead-times +#'smooth_ano_exp <- Smoothing(ano_exp, runmean_months, dim_to_smooth) +#'smooth_ano_obs <- Smoothing(ano_obs, runmean_months, dim_to_smooth) +#'dim_to_mean <- 2 # Mean along members +#'required_complete_row <- 3 # Discard start dates that contain NA along lead-times +#'leadtimes_per_startdate <- 60 +#'rms <- RMS(Mean1Dim(smooth_ano_exp, dim_to_mean), +#' Mean1Dim(smooth_ano_obs, dim_to_mean), +#' compROW = required_complete_row, +#' limits = c(ceiling((runmean_months + 1) / 2), +#' leadtimes_per_startdate - floor(runmean_months / 2))) +#'smooth_ano_exp_m_sub <- smooth_ano_exp - InsertDim(Mean1Dim(smooth_ano_exp, 2, +#' narm = TRUE), 2, dim(smooth_ano_exp)[2]) +#'spread <- Spread(smooth_ano_exp_m_sub, c(2, 3)) +#'Plot2VarsVsLTime(InsertDim(rms[, , , ], 1, 1), spread$sd, +#' toptitle = 'RMSE and spread', monini = 11, freq = 12, +#' listexp = c('CMIP5 IC3'), listvar = c('RMSE', 'spread'), +#' fileout = 'plot2vars.eps') +#' +#'@importFrom grDevices png jpeg postscript pdf svg bmp tiff postscript dev.cur dev.new dev.off +#'@importFrom stats ts +#'@export Plot2VarsVsLTime <- function(var1, var2, toptitle = '', ytitle = '', monini = 1, freq = 12, nticks = NULL, limits = NULL, listexp = c('exp1', 'exp2', 'exp3'), listvars = c('var1', diff --git a/R/PlotACC.R b/R/PlotACC.R index 3f499e7157b31e49a6a93bd8948830c33dc587c2..bff6511ad2bb0d556221b15aaf5b8dfd04103296 100644 --- a/R/PlotACC.R +++ b/R/PlotACC.R @@ -1,3 +1,95 @@ +#'Plot Plumes/Timeseries Of Anomaly Correlation Coefficients +#' +#'Plots plumes/timeseries of ACC from an array with dimensions +#'(output from \code{ACC()}): \cr +#'c(nexp, nobs, nsdates, nltime, 4)\cr +#'where the fourth dimension is of length 4 and contains the lower limit of +#'the 95\% confidence interval, the ACC, the upper limit of the 95\% +#'confidence interval and the 95\% significance level given by a one-sided +#'T-test. +#' +#'@param ACC ACC matrix with with dimensions:\cr +#' c(nexp, nobs, nsdates, nltime, 4)\cr +#' with the fourth dimension of length 4 containing the lower limit of the +#' 95\% confidence interval, the ACC, the upper limit of the 95\% confidence +#' interval and the 95\% significance level. +#'@param sdates List of startdates: c('YYYYMMDD','YYYYMMDD'). +#'@param toptitle Main title, optional. +#'@param sizetit Multiplicative factor to scale title size, optional. +#'@param ytitle Title of Y-axis for each experiment: c('',''), optional. +#'@param limits c(lower limit, upper limit): limits of the Y-axis, optional. +#'@param legends List of flags (characters) to be written in the legend, +#' optional. +#'@param freq 1 = yearly, 12 = monthly, 4 = seasonal, ... Default: 12. +#'@param biglab TRUE/FALSE for presentation/paper plot, Default = FALSE. +#'@param fill TRUE/FALSE if filled confidence interval. Default = FALSE. +#'@param linezero TRUE/FALSE if a line at y=0 should be added. Default = FALSE. +#'@param points TRUE/FALSE if points instead of lines. Default = TRUE.\cr +#' Must be TRUE if only 1 leadtime. +#'@param vlines List of x location where to add vertical black lines, optional. +#'@param fileout Name of output file. Extensions allowed: eps/ps, jpeg, png, +#' pdf, bmp and tiff. \cr +#' Default = 'output_PlotACC.eps' +#'@param width File width, in the units specified in the parameter size_units +#' (inches by default). Takes 8 by default. +#'@param height File height, in the units specified in the parameter +#' size_units (inches by default). Takes 5 by default. +#'@param size_units Units of the size of the device (file or window) to plot +#' in. Inches ('in') by default. See ?Devices and the creator function of the +#' corresponding device. +#'@param res Resolution of the device (file or window) to plot in. See +#' ?Devices and the creator function of the corresponding device. +#'@param \dots Arguments to be passed to the method. Only accepts the following +#' graphical parameters:\cr +#' adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt +#' csi cxy err family fg fig fin font font.axis font.lab font.main font.sub +#' lend lheight ljoin lmitre mar mex mfcol mfrow mfg mkh oma omd omi page +#' plt smo srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog\cr +#' For more information about the parameters see `par`. +#' +#'@keywords dynamic +#'@author History:\cr +#'0.1 - 2013-08 (V. Guemas, \email{virginie.guemas@@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to CRAN +#'@examples +#'# See examples on Load() to understand the first lines in this example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' leadtimemin = 1, leadtimemax = 4, output = 'lonlat', +#' latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' leadtimemin = 1, +#' leadtimemax = 4, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'sampleData$mod <- Season(sampleData$mod, 4, 11, 12, 2) +#'sampleData$obs <- Season(sampleData$obs, 4, 11, 12, 2) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'ano_exp <- Ano(sampleData$mod, clim$clim_exp) +#'ano_obs <- Ano(sampleData$obs, clim$clim_obs) +#'acc <- ACC(Mean1Dim(sampleData$mod, 2), +#' Mean1Dim(sampleData$obs, 2)) +#'PlotACC(acc$ACC, startDates, toptitle = "Anomaly Correlation Coefficient") +#' +#'@importFrom grDevices dev.cur dev.new dev.off +#'@importFrom stats ts +#'@export PlotACC <- function(ACC, sdates, toptitle = "", sizetit = 1, ytitle = "", limits = NULL, legends = NULL, freq = 12, biglab = FALSE, fill = FALSE, linezero = FALSE, points = TRUE, vlines = NULL, diff --git a/R/PlotAno.R b/R/PlotAno.R index a302e00132566a301ab2c8a870967cd31b3da60d..cc897a923c11844a09ac28a6eeaf8bd1469f9dc6 100644 --- a/R/PlotAno.R +++ b/R/PlotAno.R @@ -1,3 +1,78 @@ +#'Plot Raw Or Smoothed Anomalies +#' +#'Plots timeseries of raw or smoothed anomalies of any variable output from +#'\code{Load()} or \code{Ano()} or or \code{Ano_CrossValid()} or +#'\code{Smoothing()}. +#' +#'@param exp_ano Array containing the experimental data:\cr +#' c(nmod/nexp, nmemb/nparam, nsdates, nltime). +#'@param obs_ano Optional matrix containing the observational data:\cr +#' c(nobs, nmemb, nsdates, nltime) +#'@param sdates List of starting dates: c('YYYYMMDD','YYYYMMDD'). +#'@param toptitle Main title for each experiment: c('',''), optional. +#'@param ytitle Title of Y-axis for each experiment: c('',''), optional. +#'@param limits c(lower limit, upper limit): limits of the Y-axis, optional. +#'@param legends List of observational dataset names, optional. +#'@param freq 1 = yearly, 12 = monthly, 4 = seasonal, ... Default: 12. +#'@param biglab TRUE/FALSE for presentation/paper plot. Default = FALSE. +#'@param fill TRUE/FALSE if the spread between members should be filled. +#' Default = TRUE. +#'@param memb TRUE/FALSE if all members/only the ensemble-mean should be +#' plotted.\cr +#' Default = TRUE. +#'@param ensmean TRUE/FALSE if the ensemble-mean should be plotted. +#' Default = TRUE. +#'@param linezero TRUE/FALSE if a line at y=0 should be added. +#' Default = FALSE. +#'@param points TRUE/FALSE if points instead of lines should be shown. +#' Default = FALSE. +#'@param vlines List of x location where to add vertical black lines, optional. +#'@param sizetit Multiplicative factor to scale title size, optional. +#'@param fileout Name of the output file for each experiment: c('',''). +#' Extensions allowed: eps/ps, jpeg, png, pdf, bmp and tiff. If filenames +#' with different extensions are passed, it will be considered only the first +#' one and it will be extended to the rest. \cr +#' Default = c('output1_plotano.eps', 'output2_plotano.eps', +#' 'output3_plotano.eps', 'output4_plotano.eps', +#' 'output5_plotano.eps') +#'@param width File width, in the units specified in the parameter size_units +#' (inches by default). Takes 8 by default. +#'@param height File height, in the units specified in the parameter +#' size_units (inches by default). Takes 5 by default. +#'@param size_units Units of the size of the device (file or window) to plot +#' in. Inches ('in') by default. See ?Devices and the creator function of the +#' corresponding device. +#'@param res Resolution of the device (file or window) to plot in. See +#' ?Devices and the creator function of the corresponding device. +#'@param \dots Arguments to be passed to the method. Only accepts the following +#' graphical parameters:\cr +#' adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt +#' csi cxy err family fg fig font font.axis font.lab font.main font.sub lend +#' lheight ljoin lmitre mar mex mfcol mfrow mfg mkh oma omd omi page plt smo +#' srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog \cr +#' For more information about the parameters see `par`. +#' +#'@keywords dynamic +#'@author History:\cr +#'0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to CRAN +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'ano_exp <- Ano(sampleData$mod, clim$clim_exp) +#'ano_obs <- Ano(sampleData$obs, clim$clim_obs) +#'runmean_nb_months <- 12 +#'dim_to_smooth <- 4 # Smooth along lead-times +#'smooth_ano_exp <- Smoothing(ano_exp, runmean_nb_months, dim_to_smooth) +#'smooth_ano_obs <- Smoothing(ano_obs, runmean_nb_months, dim_to_smooth) +#'PlotAno(smooth_ano_exp, smooth_ano_obs, startDates, +#' toptitle = paste('smoothed anomalies'), ytitle = c('K', 'K', 'K'), +#' legends = 'ERSST', biglab = FALSE, fileout = 'tos_ano.eps') +#' +#'@importFrom grDevices dev.cur dev.new dev.off +#'@importFrom stats ts +#'@export PlotAno <- function(exp_ano, obs_ano = NULL, sdates, toptitle = rep('', 15), ytitle = rep('', 15), limits = NULL, legends = NULL, freq = 12, biglab = FALSE, fill = TRUE, memb = TRUE, diff --git a/R/PlotBoxWhisker.R b/R/PlotBoxWhisker.R index 1bf41ff17536b462ee81ee643f2aa08215234a8a..1574522c0a102c7723506669ddd8de3de68b255f 100644 --- a/R/PlotBoxWhisker.R +++ b/R/PlotBoxWhisker.R @@ -1,3 +1,106 @@ +#'Box-And-Whisker Plot of Time Series with Ensemble Distribution +#' +#'Produce time series of box-and-whisker plot showing the distribution of the +#'members of a forecast vs. the observed evolution. The correlation between +#'forecast and observational data is calculated and displayed. Only works for +#'n-monthly to n-yearly time series. +#' +#'@param exp Forecast array of multi-member time series, e.g., the NAO index +#' of one experiment. The expected dimensions are +#' c(members, start dates/forecast horizons). A vector with only the time +#' dimension can also be provided. Only monthly or lower frequency time +#' series are supported. See parameter freq. +#'@param obs Observational vector or array of time series, e.g., the NAO index +#' of the observations that correspond the forecast data in \code{exp}. +#' The expected dimensions are c(start dates/forecast horizons) or +#' c(1, start dates/forecast horizons). Only monthly or lower frequency time +#' series are supported. See parameter freq. +#'@param toptitle Character string to be drawn as figure title. +#'@param ytitle Character string to be drawn as y-axis title. +#'@param monini Number of the month of the first time step, from 1 to 12. +#'@param yearini Year of the first time step. +#'@param freq Frequency of the provided time series: 1 = yearly, 12 = monthly, +# 4 = seasonal, ... Default = 12. +#'@param expname Experimental dataset name. +#'@param obsname Name of the observational reference dataset. +#'@param drawleg TRUE/FALSE: whether to draw the legend or not. +#'@param fileout Name of output file. Extensions allowed: eps/ps, jpeg, png, +#' pdf, bmp and tiff. \cr +#' Default = 'output_PlotBox.ps'. +#'@param width File width, in the units specified in the parameter size_units +#' (inches by default). Takes 8 by default. +#'@param height File height, in the units specified in the parameter +#' size_units (inches by default). Takes 5 by default. +#'@param size_units Units of the size of the device (file or window) to plot +#' in. Inches ('in') by default. See ?Devices and the creator function of the +#' corresponding device. +#'@param res Resolution of the device (file or window) to plot in. See +#' ?Devices and the creator function of the corresponding device. +#'@param ... Arguments to be passed to the method. Only accepts the following +#' graphical parameters:\cr +#' ann ask bg cex.lab cex.sub cin col.axis col.lab col.main col.sub cra crt +#' csi cxy err family fg fig font font.axis font.lab font.main font.sub lend +#' lheight ljoin lmitre mex mfcol mfrow mfg mkh oma omd omi page pin plt pty +#' smo srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog \cr +#' For more information about the parameters see `par`. +#' +#'@return Generates a file at the path specified via \code{fileout}. +#' +#'@seealso EOF, ProjectField, NAO +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2013-09 (F. Lienert, \email{flienert@@ic3.cat}) - Original code\cr +#'0.2 - 2015-03 (L. Batte, \email{lauriane.batte@@ic3.cat}) - Removed all\cr +#' normalization for sake of clarity. +#'1.0 - 2016-03 (N. Manubens, \email{nicolau.manubens@@bsc.es}) - Formatting to R CRAN +#'@examples +#'# See examples on Load() to understand the first lines in this example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' leadtimemin = 1, leadtimemax = 4, output = 'lonlat', +#' latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' leadtimemin = 1, +#' leadtimemax = 4, +#' output = 'lonlat', +#' latmin = 20, latmax = 80, +#' lonmin = -80, lonmax = 40) +#'# No example data is available over NAO region, so in this example we will +#'# tweak the available data. In a real use case, one can Load() the data over +#'# NAO region directly. +#'sampleData$lon[] <- c(40, 280, 340) +#'attr(sampleData$lon, 'first_lon') <- 280 +#'attr(sampleData$lon, 'last_lon') <- 40 +#'attr(sampleData$lon, 'data_across_gw') <- TRUE +#'sampleData$lat[] <- c(20, 80) +#'attr(sampleData$lat, 'first_lat') <- 20 +#'attr(sampleData$lat, 'last_lat') <- 80 +#' } +#'# Now ready to compute the EOFs and project on, for example, the first +#'# variability mode. +#'ano <- Ano_CrossValid(sampleData$mod, sampleData$obs) +#'nao <- NAO(ano$ano_exp, ano$ano_obs, sampleData$lon, sampleData$lat) +#'# Finally plot the nao index +#'PlotBoxWhisker(nao$NAO_exp, nao$NAO_obs, "NAO index, DJF", "NAO index (PC1) TOS", +#' monini = 12, yearini = 1985, freq = 1, "Exp. A", "Obs. X") +#' +#'@importFrom grDevices dev.cur dev.new dev.off +#'@importFrom stats cor +#'@export PlotBoxWhisker <- function(exp, obs, toptitle = '', ytitle = '', monini = 1, yearini = 0, freq = 1, expname = "exp 1", obsname = "obs 1", drawleg = TRUE, diff --git a/R/PlotClim.R b/R/PlotClim.R index 7ce30c0dbcb360b70eacdac85493f05dc97bfe9e..e7e6ac313ebc5df09a2701b2e4451dbfeecfe89b 100644 --- a/R/PlotClim.R +++ b/R/PlotClim.R @@ -1,3 +1,61 @@ +#'Plots Climatologies +#' +#'Plots climatologies as a function of the forecast time for any index output +#'from \code{Clim()} and organized in matrix with dimensions:\cr +#'c(nmod/nexp, nmemb/nparam, nltime) or c(nmod/nexp, nltime) for the +#'experiment data\cr +#'c(nobs, nmemb, nltime) or c(nobs, nltime) for the observational data +#' +#'@param exp_clim Matrix containing the experimental data with dimensions:\cr +#' c(nmod/nexp, nmemb/nparam, nltime) or c(nmod/nexp, nltime) +#'@param obs_clim Matrix containing the observational data (optional) with +#' dimensions:\cr +#' c(nobs, nmemb, nltime) or c(nobs, nltime) +#'@param toptitle Main title, optional. +#'@param ytitle Title of Y-axis, optional. +#'@param monini Starting month between 1 and 12. Default = 1. +#'@param freq 1 = yearly, 12 = monthly, 4 = seasonal, ... Default = 12. +#'@param limits c(lower limit, upper limit): limits of the Y-axis, optional. +#'@param listexp List of experiment names, optional. +#'@param listobs List of observational dataset names, optional. +#'@param biglab TRUE/FALSE for presentation/paper plot. Default = FALSE. +#'@param leg TRUE/FALSE to plot the legend or not. +#'@param sizetit Multiplicative factor to scale title size, optional. +#'@param width File width, in the units specified in the parameter size_units +#' (inches by default). Takes 8 by default. +#'@param height File height, in the units specified in the parameter +#' size_units (inches by default). Takes 5 by default. +#'@param size_units Units of the size of the device (file or window) to plot +#' in. Inches ('in') by default. See ?Devices and the creator function of the +#' corresponding device. +#'@param res Resolution of the device (file or window) to plot in. See +#' ?Devices and the creator function of the corresponding device. +#'@param fileout Name of output file. Extensions allowed: eps/ps, jpeg, png, +#' pdf, bmp and tiff. \cr +#' Default = 'output_plotclim.eps'. +#'@param ... Arguments to be passed to the method. Only accepts the following +#' graphical parameters:\cr +#' adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt +#' csi cxy err family fg fig font font.axis font.lab font.main font.sub lend +#' lheight ljoin lmitre mar mex mfcol mfrow mfg mkh oma omd omi page pch plt +#' smo srt tck usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog \cr +#' For more information about the parameters see `par`. +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to CRAN +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'PlotClim(clim$clim_exp, clim$clim_obs, toptitle = paste('climatologies'), +#' ytitle = 'K', monini = 11, listexp = c('CMIP5 IC3'), +#' listobs = c('ERSST'), biglab = FALSE, fileout = 'tos_clim.eps') +#' +#'@importFrom grDevices dev.cur dev.new dev.off +#'@importFrom stats ts +#'@export PlotClim <- function(exp_clim, obs_clim = NULL, toptitle = '', ytitle = '', monini = 1, freq = 12, limits = NULL, listexp = c('exp1', 'exp2', 'exp3'), diff --git a/R/PlotEquiMap.R b/R/PlotEquiMap.R index 51599dc70f90f5440f61f0fab8bae9a5e3cf5663..8f3fcb9ab0f754dc7184784d9a4050e212a22e08 100644 --- a/R/PlotEquiMap.R +++ b/R/PlotEquiMap.R @@ -1,3 +1,220 @@ +#'Maps A Two-Dimensional Variable On A Cylindrical Equidistant Projection +#' +#'Map longitude-latitude array (on a regular rectangular or gaussian grid) +#'on a cylindrical equidistant latitude and longitude projection with coloured +#'grid cells. Only the region for which data has been provided is displayed. +#'A colour bar (legend) can be plotted and adjusted. It is possible to draw +#'superimposed arrows, dots, symbols, contour lines and boxes. A number of +#'options is provided to adjust the position, size and colour of the +#'components. This plot function is compatible with figure layouts if colour +#'bar is disabled. +#' +#'@param var Array with the values at each cell of a grid on a regular +#' rectangular or gaussian grid. The array is expected to have two +#' dimensions: c(latitude, longitude). Longitudes can be in ascending or +#' descending order and latitudes in any order. It can contain NA values +#' (coloured with 'colNA'). Arrays with dimensions c(longitude, latitude) +#' will also be accepted but 'lon' and 'lat' will be used to disambiguate so +#' this alternative is not appropriate for square arrays. +#'@param lon Numeric vector of longitude locations of the cell centers of the +#' grid of 'var', in ascending or descending order (same as 'var'). Expected +#' to be regularly spaced, within either of the ranges [-180, 180] or +#' [0, 360]. Data for two adjacent regions split by the limits of the +#' longitude range can also be provided, e.g. \code{lon = c(0:50, 300:360)} +#' ('var' must be provided consitently). +#'@param lat Numeric vector of latitude locations of the cell centers of the +#' grid of 'var', in any order (same as 'var'). Expected to be from a regular +#' rectangular or gaussian grid, within the range [-90, 90]. +#'@param varu Array of the zonal component of wind/current/other field with +#' the same dimensions as 'var'. +#'@param varv Array of the meridional component of wind/current/other field +#' with the same dimensions as 'var'. +#'@param toptitle Top title of the figure, scalable with parameter +#' 'title_scale'. +#'@param sizetit Scale factor for the figure top title provided in parameter +#' 'toptitle'. Deprecated. Use 'title_scale' instead. +#'@param units Title at the top of the colour bar, most commonly the units of +#' the variable provided in parameter 'var'. +#'@param brks,cols,bar_limits,triangle_ends Usually only providing 'brks' is +#' enough to generate the desired colour bar. These parameters allow to +#' define n breaks that define n - 1 intervals to classify each of the values +#' in 'var'. The corresponding grid cell of a given value in 'var' will be +#' coloured in function of the interval it belongs to. These parameters are +#' sent to \code{ColorBar()} to generate the breaks and colours. Additional +#' colours for values beyond the limits of the colour bar are also generated +#' and applied to the plot if 'bar_limits' or 'brks' and 'triangle_ends' are +#' properly provided to do so. See ?ColorBar for a full explanation. +#'@param col_inf,col_sup,colNA Colour identifiers to colour the values in +#' 'var' that go beyond the extremes of the colour bar and to colour NA +#' values, respectively. 'colNA' takes attr(cols, 'na_color') if available by +#' default, where cols is the parameter 'cols' if provided or the vector of +#' colors returned by 'color_fun'. If not available, it takes 'pink' by +#' default. 'col_inf' and 'col_sup' will take the value of 'colNA' if not +#' specified. See ?ColorBar for a full explanation on 'col_inf' and 'col_sup'. +#'@param color_fun,subsampleg,bar_extra_labels,draw_bar_ticks,draw_separators,triangle_ends_scale,bar_label_digits,bar_label_scale,units_scale,bar_tick_scale,bar_extra_margin Set of parameters to control the visual +#' aspect of the drawn colour bar. See ?ColorBar for a full explanation. +#'@param square Logical value to choose either to draw a coloured square for +#' each grid cell in 'var' (TRUE; default) or to draw contour lines and fill +#' the spaces in between with colours (FALSE). In the latter case, +#' 'filled.continents' will take the value FALSE if not specified. +#'@param filled.continents Colour to fill in drawn projected continents. +#' Takes the value gray(0.5) by default or, if 'square = FALSE', takes the +#' value FALSE. If set to FALSE, continents are not filled in. +#'@param coast_color Colour of the coast line of the drawn projected continents. +#' Takes the value gray(0.5) by default. +#'@param coast_width Line width of the coast line of the drawn projected +#' continents. Takes the value 1 by default. +#'@param contours Array of same dimensions as 'var' to be added to the plot +#' and displayed with contours. Parameter 'brks2' is required to define the +#' magnitude breaks for each contour curve. Disregarded if 'square = FALSE'. +#'@param brks2 Vector of magnitude breaks where to draw contour curves for the +#' array provided in 'contours' or if 'square = FALSE'. +#'@param contour_lwd Line width of the contour curves provided via 'contours' +#' and 'brks2', or if 'square = FALSE'. +#'@param contour_color Line color of the contour curves provided via 'contours' +#' and 'brks2', or if 'square = FALSE'. +#'@param contour_lty Line type of the contour curves. Takes 1 (solid) by +#' default. See help on 'lty' in par() for other accepted values. +#'@param contour_label_scale Scale factor for the superimposed labels when +#' drawing contour levels. +#'@param dots Array of same dimensions as 'var' or with dimensions +#' c(n, dim(var)), where n is the number of dot/symbol layers to add to the +#' plot. A value of TRUE at a grid cell will draw a dot/symbol on the +#' corresponding square of the plot. By default all layers provided in 'dots' +#' are plotted with dots, but a symbol can be specified for each of the +#' layers via the parameter 'dot_symbol'. +#'@param dot_symbol Single character/number or vector of characters/numbers +#' that correspond to each of the symbol layers specified in parameter 'dots'. +#' If a single value is specified, it will be applied to all the layers in +#' 'dots'. Takes 15 (centered square) by default. See 'pch' in par() for +#' additional accepted options. +#'@param dot_size Scale factor for the dots/symbols to be plotted, specified +#' in 'dots'. If a single value is specified, it will be applied to all +#' layers in 'dots'. Takes 1 by default. +#'@param arr_subsamp Subsampling factor to select a subset of arrows in +#' 'varu' and 'varv' to be drawn. Only one out of arr_subsamp arrows will +#' be drawn. Takes 1 by default. +#'@param arr_scale Scale factor for drawn arrows from 'varu' and 'varv'. +#' Takes 1 by default. +#'@param arr_ref_len Length of the refence arrow to be drawn as legend at the +#' bottom of the figure (in same units as 'varu' and 'varv', only affects the +#' legend for the wind or variable in these arrays). Defaults to 15. +#'@param arr_units Units of 'varu' and 'varv', to be drawn in the legend. +#' Takes 'm/s' by default. +#'@param arr_scale_shaft Parameter for the scale of the shaft of the arrows +#' (which also depend on the number of figures and the arr_scale parameter). +#' Defaults to 1. +#'@param arr_scale_shaft_angle Parameter for the scale of the angle of the +#' shaft of the arrows (which also depend on the number of figure and the +#' arr_scale parameter). Defaults to 1. +#'@param axelab Whether to draw longitude and latitude axes or not. +#' TRUE by default. +#'@param labW Whether to label the longitude axis with a 'W' instead of minus +#' for negative values. Defaults to FALSE. +#'@param intylat Interval between latitude ticks on y-axis, in degrees. +#' Defaults to 20. +#'@param intxlon Interval between latitude ticks on x-axis, in degrees. +#' Defaults to 20. +#'@param axes_tick_scale Scale factor for the tick lines along the longitude +#' and latitude axes. +#'@param axes_label_scale Scale factor for the labels along the longitude +#' and latitude axes. +#'@param drawleg Whether to plot a color bar (legend, key) or not. Defaults to +#' TRUE. It is not possible to plot the colour bar if 'add = TRUE'. Use +#' ColorBar() and the return values of PlotEquiMap() instead. +#'@param boxlim Limits of a box to be added to the plot, in degrees: +#' c(x1, y1, x2, y2). A list with multiple box specifications can also be +#' provided. +#'@param boxcol Colour of the box lines. A vector with a colour for each of +#' the boxes is also accepted. Defaults to 'purple2'. +#'@param boxlwd Line width of the box lines. A vector with a line width for +#' each of the boxes is also accepted. Defaults to 5. +#'@param margin_scale Scale factor for the margins around the map plot, with +#' the format c(y1, x1, y2, x2). Defaults to rep(1, 4). If drawleg = TRUE, +#' then margin_scale[1] is subtracted 1 unit. +#'@param title_scale Scale factor for the figure top title. Defaults to 1. +#'@param numbfig Number of figures in the layout the plot will be put into. +#' A higher numbfig will result in narrower margins and smaller labels, +#' axe labels, ticks, thinner lines, ... Defaults to 1. +#'@param fileout File where to save the plot. If not specified (default) a +#' graphics device will pop up. Extensions allowed: eps/ps, jpeg, png, pdf, +#' bmp and tiff. +#'@param width File width, in the units specified in the parameter size_units +#' (inches by default). Takes 8 by default. +#'@param height File height, in the units specified in the parameter +#' size_units (inches by default). Takes 5 by default. +#'@param size_units Units of the size of the device (file or window) to plot +#' in. Inches ('in') by default. See ?Devices and the creator function of +#' the corresponding device. +#'@param res Resolution of the device (file or window) to plot in. See +#' ?Devices and the creator function of the corresponding device. +#'@param \dots Arguments to be passed to the method. Only accepts the following +#' graphical parameters:\cr +#' adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt +#' csi cxy err family fg font font.axis font.lab font.main font.sub lend +#' lheight ljoin lmitre mex mfcol mfrow mfg mkh omd omi page pch pin plt +#' pty smo srt tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog \cr +#' For more information about the parameters see `par`. +#' +#'@return +#'\item{brks}{ +#' Breaks used for colouring the map (and legend if drawleg = TRUE). +#'} +#'\item{cols}{ +#' Colours used for colouring the map (and legend if drawleg = TRUE). Always +#' of length length(brks) - 1. +#'} +#'\item{col_inf}{ +#' Colour used to draw the lower triangle end in the colour bar (NULL if not +#' drawn at all). +#' } +#'\item{col_sup}{ +#' Colour used to draw the upper triangle end in the colour bar (NULL if not +#' drawn at all). +#'} +#' +#'@keywords dynamic +#'@author History:\cr +#' 0.1 - 2011-11 (V. Guemas, \email{virginie.guemas@@ic3.cat}) - Original code\cr +#' 0.2 - 2013-04 (R. Saurral \email{ramiro.saurral@@ic3.cat}) - LabW\cr +#' 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to R CRAN\cr +#' 1.1 - 2013-09 (C. Prodhomme, \email{chloe.prodhomme@@ic3.cat}) - add winds\cr +#' 1.2 - 2016-08 (N. Manubens, \email{nicolau.manubens@@bsc.es}) - Refactored and added features, +#' and adapted to new ColorBar. +#'@examples +#'# See examples on Load() to understand the first lines in this example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' leadtimemin = 1, leadtimemax = 4, output = 'lonlat', +#' latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' leadtimemin = 1, +#' leadtimemax = 4, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'PlotEquiMap(sampleData$mod[1, 1, 1, 1, , ], sampleData$lon, sampleData$lat, +#' toptitle = 'Predicted sea surface temperature for Nov 1960 from 1st Nov', +#' sizetit = 0.5) +#'@import graphics GEOmap geomapdata maps +#'@importFrom grDevices dev.cur dev.new dev.off gray +#'@importFrom stats cor +#'@export PlotEquiMap <- function(var, lon, lat, varu = NULL, varv = NULL, toptitle = NULL, sizetit = NULL, units = NULL, brks = NULL, cols = NULL, bar_limits = NULL, diff --git a/R/PlotLayout.R b/R/PlotLayout.R index 0eb1254e8da6fbfed977ed2ee2057f742b2b8ed9..b5239f27a6b834ba3953d3e26ac6fb4d222ae8c8 100644 --- a/R/PlotLayout.R +++ b/R/PlotLayout.R @@ -1,3 +1,203 @@ +#'Arrange and Fill Multi-Pannel Layouts With Optional Colour Bar +#' +#'This function takes an array or list of arrays and loops over each of them +#'to plot all the sub-arrays they contain on an automatically generated +#'multi-pannel layout. A different plot function (not necessarily from +#'s2dverification) can be applied over each of the provided arrays. The input +#'dimensions of each of the functions have to be specified, either with the +#'names or the indices of the corresponding input dimensions. It is possible +#'to draw a common colour bar at any of the sides of the multi-pannel for all +#'the s2dverification plots that use a colour bar. Common plotting arguments +#'for all the arrays in 'var' can be specified via the '...' parameter, and +#'specific plotting arguments for each array can be fully adjusted via +#''special_args'. It is possible to draw titles for each of the figures, +#'layout rows, layout columns and for the whole figure. A number of parameters +#'is provided in order to adjust the position, size and colour of the +#'components. Blank cells can be forced to appear and later be filled in +#'manually with customized plots.\cr +#'This function pops up a blank new device and fills it in, so it cannot be +#'nested in complex layouts. +#' +#'@param fun Plot function (or name of the function) to be called on the +#' arrays provided in 'var'. If multiple arrays are provided in 'var', a +#' vector of as many function names (character strings!) can be provided in +#' 'fun', one for each array in 'var'. +#'@param plot_dims Numeric or character string vector with identifiers of the +#' input plot dimensions of the plot function specified in 'fun'. If +#' character labels are provided, names(dim(var)) or attr('dimensions', var) +#' will be checked to locate the dimensions. As many plots as +#' prod(dim(var)[-plot_dims]) will be generated. If multiple arrays are +#' provided in 'var', 'plot_dims' can be sent a list with a vector of plot +#' dimensions for each. If a single vector is provided, it will be used for +#' all the arrays in 'var'. +#'@param var Multi-dimensional array with at least the dimensions expected by +#' the specified plot function in 'fun'. The dimensions reqired by the +#' function must be specified in 'plot_dims'. The dimensions can be +#' disordered and will be reordered automatically. Dimensions can optionally +#' be labelled in order to refer to them with names in 'plot_dims'. All the +#' available plottable sub-arrays will be automatically plotted and arranged +#' in consecutive cells of an automatically arranged layout. A list of +#' multiple (super-)arrays can be specified. The process will be repeated for +#' each of them, by default applying the same plot function to all of them +#' or, if properly specified in 'fun', a different plot function will be +#' applied to each of them. NAs can be passed to the list: a NA will yield a +#' blank cell in the layout, which can be populated after +#' (see .SwitchToFigure). +#'@param \dots Parameters to be sent to the plotting function 'fun'. If +#' multiple arrays are provided in 'var' and multiple functions are provided +#' in 'fun', the parameters provided through \dots will be sent to all the +#' plot functions, as common parameters. To specify concrete arguments for +#' each of the plot functions see parameter 'special_args'. +#'@param special_args List of sub-lists, each sub-list having specific extra +#' arguments for each of the plot functions provided in 'fun'. If you want to +#' fix a different value for each plot in the layout you can do so by +#' a) splitting your array into a list of sub-arrays (each with the data for +#' one plot) and providing it as parameter 'var', +#' b) providing a list of named sub-lists in 'special_args', where the names +#' of each sub-list match the names of the parameters to be adjusted, and +#' each value in a sub-list contains the value of the corresponding parameter. +#'@param nrow Numeric value to force the number of rows in the automatically +#' generated layout. If higher than the required, this will yield blank cells +#' in the layout (which can then be populated). If lower than the required +#' the function will stop. By default it is configured to arrange the layout +#' in a shape as square as possible. Blank cells can be manually populated +#' after with customized plots (see SwitchTofigure). +#'@param ncol Numeric value to force the number of columns in the +#' automatically generated layout. If higher than the required, this will +#' yield blank cells in the layout (which can then be populated). If lower +#' than the required the function will stop. By default it is configured to +#' arrange the layout in a shape as square as possible. Blank cells can be +#' manually populated after with customized plots (see SwitchTofigure). +#'@param toptitle Topt title for the multi-pannel. Blank by default. +#'@param row_titles Character string vector with titles for each of the rows +#' in the layout. Blank by default. +#'@param col_titles Character string vector with titles for each of the +#' columns in the layout. Blank by default. +#'@param bar_scale Scale factor for the common colour bar. Takes 1 by default. +#'@param title_scale Scale factor for the multi-pannel title. Takes 1 by +#' default. +#'@param title_margin_scale Scale factor for the margins surrounding the top +#' title. Takes 1 by default. +#'@param title_left_shift_scale When plotting row titles, a shift is added +#' to the horizontal positioning of the top title in order to center it to +#' the region of the figures (without taking row titles into account). This +#' shift can be reduced. A value of 0 will remove the shift completely, +#' centering the title to the total width of the device. This parameter will +#' be disregarded if no 'row_titles' are provided. +#'@param subtitle_scale Scale factor for the row titles and column titles +#' (specified in 'row_titles' and 'col_titles'). Takes 1 by default. +#'@param subtitle_margin_scale Scale factor for the margins surrounding the +#' subtitles. Takes 1 by default. +#'@param units Title at the top of the colour bar, most commonly the units of +#' the variable provided in parameter 'var'. +#'@param brks,cols,bar_limits,triangle_ends Usually only providing 'brks' is +#' enough to generate the desired colour bar. These parameters allow to +#' define n breaks that define n - 1 intervals to classify each of the values +#' in 'var'. The corresponding grid cell of a given value in 'var' will be +#' coloured in function of the interval it belongs to. These parameters are +#' sent to \code{ColorBar()} to generate the breaks and colours. Additional +#' colours for values beyond the limits of the colour bar are also generated +#' and applied to the plot if 'bar_limits' or 'brks' and 'triangle_ends' are +#' properly provided to do so. See ?ColorBar for a full explanation. +#'@param col_inf,col_sup Colour identifiers to colour the values in 'var' that +#' go beyond the extremes of the colour bar and to colour NA values, +#' respectively. 'colNA' takes 'white' by default. 'col_inf' and 'col_sup' +#' will take the value of 'colNA' if not specified. See ?ColorBar for a full +#' explanation on 'col_inf' and 'col_sup'. +#'@param color_fun,subsampleg,bar_extra_labels,draw_bar_ticks,draw_separators,triangle_ends_scale,bar_label_digits,bar_label_scale,units_scale,bar_tick_scale,bar_extra_margin Set of parameters to control the visual aspect of the drawn colour bar. See ?ColorBar for a full explanation. +#'@param drawleg Where to draw the common colour bar. Can take values TRUE, +#' FALSE or:\cr +#' 'up', 'u', 'U', 'top', 't', 'T', 'north', 'n', 'N'\cr +#' 'down', 'd', 'D', 'bottom', 'b', 'B', 'south', 's', 'S' (default)\cr +#' 'right', 'r', 'R', 'east', 'e', 'E'\cr +#' 'left', 'l', 'L', 'west', 'w', 'W' +#'@param titles Character string vector with titles for each of the figures in +#' the multi-pannel, from top-left to bottom-right. Blank by default. +#'@param bar_left_shift_scale When plotting row titles, a shift is added to +#' the horizontal positioning of the colour bar in order to center it to the +#' region of the figures (without taking row titles into account). This shift +#' can be reduced. A value of 0 will remove the shift completely, centering +#' the colour bar to the total width of the device. This parameter will be +#' disregarded if no 'row_titles' are provided. +#'@param extra_margin Extra margins to be added around the layout, in the +#' format c(y1, x1, y2, x2). The units are margin lines. Takes rep(0, 4) +#' by default. +#'@param fileout File where to save the plot. If not specified (default) a +#' graphics device will pop up. Extensions allowed: eps/ps, jpeg, png, pdf, +#' bmp and tiff. +#'@param width Width in inches of the multi-pannel. 7 by default, or 11 if +#' 'fielout' has been specified. +#'@param height Height in inches of the multi-pannel. 7 by default, or 11 if +#' 'fileout' has been specified. +#'@param size_units Units of the size of the device (file or window) to plot +#' in. Inches ('in') by default. See ?Devices and the creator function of +#' the corresponding device. +#'@param res Resolution of the device (file or window) to plot in. See +#' ?Devices and the creator function of the corresponding device. +#'@param close_device Whether to close the graphics device after plotting +#' the layout and a 'fileout' has been specified. This is useful to avoid +#' closing the device when saving the layout into a file and willing to add +#' extra elements or figures. Takes TRUE by default. Disregarded if no +#' 'fileout' has been specified. +#' +#'@return +#'\item{brks}{ +#' Breaks used for colouring the map (and legend if drawleg = TRUE). +#'} +#'\item{cols}{ +#' Colours used for colouring the map (and legend if drawleg = TRUE). +#' Always of length length(brks) - 1. +#'} +#'\item{col_inf}{ +#' Colour used to draw the lower triangle end in the colour bar +#' (NULL if not drawn at all). +#'} +#'\item{col_sup}{ +#' Colour used to draw the upper triangle end in the colour bar +#' (NULL if not drawn at all). +#'} +#'\item{layout_matrix}{ +#' Underlying matrix of the layout. Useful to later set any of the layout +#' cells as current figure to add plot elements. See .SwitchToFigure. +#'} +#' +#'@keywords dynamic +#'@author History:\cr +#' 0.1 - 2016-08 (N. Manubens, \email{nicolau.manubens@@bsc.es}) - Original code +#'@examples +#'# See examples on Load() to understand the first lines in this example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' leadtimemin = 1, leadtimemax = 4, output = 'lonlat', +#' latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' leadtimemin = 1, +#' leadtimemax = 4, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'PlotLayout(PlotEquiMap, c('lat', 'lon'), sampleData$mod[1, , 1, 1, , ], +#' sampleData$lon, sampleData$lat, +#' toptitle = 'Predicted tos for Nov 1960 from 1st Nov', +#' titles = paste('Member', 1:15)) +#' +#'@importFrom grDevices dev.cur dev.new dev.off +#'@export PlotLayout <- function(fun, plot_dims, var, ..., special_args = NULL, nrow = NULL, ncol = NULL, toptitle = NULL, row_titles = NULL, col_titles = NULL, bar_scale = 1, diff --git a/R/PlotSection.R b/R/PlotSection.R index acefbdd8e55b2a532c47cec3e32216465a4aa940..46a1e70a54b5713f267d9896fbd41cc3174543df 100644 --- a/R/PlotSection.R +++ b/R/PlotSection.R @@ -1,3 +1,51 @@ +#'Plots A Vertical Section +#' +#'Plot a (longitude,depth) or (latitude,depth) section. +#' +#'@param var Matrix to plot with (longitude/latitude, depth) dimensions. +#'@param horiz Array of longitudes or latitudes. +#'@param depth Array of depths. +#'@param toptitle Title, optional. +#'@param sizetit Multiplicative factor to increase title size, optional. +#'@param units Units, optional. +#'@param brks Colour levels, optional. +#'@param cols List of colours, optional. +#'@param axelab TRUE/FALSE, label the axis. Default = TRUE. +#'@param intydep Interval between depth ticks on y-axis. Default: 200m. +#'@param intxhoriz Interval between longitude/latitude ticks on x-axis.\cr +#' Default: 20deg. +#'@param drawleg Draw colorbar. Default: TRUE. +#'@param width File width, in the units specified in the parameter size_units +#' (inches by default). Takes 8 by default. +#'@param height File height, in the units specified in the parameter +#' size_units (inches by default). Takes 5 by default. +#'@param size_units Units of the size of the device (file or window) to plot +#' in. Inches ('in') by default. See ?Devices and the creator function of the +#' corresponding device. +#'@param res Resolution of the device (file or window) to plot in. See +#' ?Devices and the creator function of the corresponding device. +#'@param fileout Name of output file. Extensions allowed: eps/ps, jpeg, png, +#' pdf, bmp and tiff. \cr +#' Default = NULL +#'@param ... Arguments to be passed to the method. Only accepts the following +#' graphical parameters:\cr +#' adj ann ask bg bty cex.lab cex.sub cin col.axis col.lab col.main col.sub +#' cra crt csi cxy err family fg fig fin font font.axis font.lab font.main +#' font.sub lend lheight ljoin lmitre lty lwd mex mfcol mfrow mfg mkh oma omd +#' omi page pch pin plt pty smo srt tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs +#' yaxt ylbias ylog \cr +#' For more information about the parameters see `par`. +#' +#'@keywords dynamic +#'@author History:\cr +#'0.1 - 2012-09 (V. Guemas, \email{virginie.guemas@@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to CRAN +#'@examples +#'sampleData <- s2dverification::sampleDepthData +#'PlotSection(sampleData$mod[1, 1, 1, 1, , ], sampleData$lat, sampleData$depth, +#' toptitle = 'temperature 1995-11 member 0') +#'@importFrom grDevices dev.cur dev.new dev.off rainbow +#'@export PlotSection <- function(var, horiz, depth, toptitle = '', sizetit = 1, units = '', brks = NULL, cols = NULL, axelab = TRUE, intydep = 200, intxhoriz = 20, drawleg = TRUE, diff --git a/R/PlotStereoMap.R b/R/PlotStereoMap.R index f14199e9b706b84f00dab398e3a803dfb7f642a1..5572f89a56b3fedb77abcf753b92f85420dca151 100644 --- a/R/PlotStereoMap.R +++ b/R/PlotStereoMap.R @@ -1,3 +1,149 @@ +#'Maps A Two-Dimensional Variable On A Polar Stereographic Projection +#' +#'Map longitude-latitude array (on a regular rectangular or gaussian grid) on +#'a polar stereographic world projection with coloured grid cells. Only the +#'region within a specified latitude interval is displayed. A colour bar +#'(legend) can be plotted and adjusted. It is possible to draw superimposed +#'dots, symbols and boxes. A number of options is provided to adjust the +#'position, size and colour of the components. This plot function is +#'compatible with figure layouts if colour bar is disabled. +#' +#'@param var Array with the values at each cell of a grid on a regular +#' rectangular or gaussian grid. The array is expected to have two dimensions: +#' c(latitude, longitude). Longitudes can be in ascending or descending order +#' and latitudes in any order. It can contain NA values (coloured with +#' 'colNA'). Arrays with dimensions c(longitude, latitude) will also be +#' accepted but 'lon' and 'lat' will be used to disambiguate so this +#' alternative is not appropriate for square arrays. +#'@param lon Numeric vector of longitude locations of the cell centers of the +#' grid of 'var', in ascending or descending order (same as 'var'). Expected +#' to be regularly spaced, within either of the ranges [-180, 180] or +#' [0, 360]. Data for two adjacent regions split by the limits of the +#' longitude range can also be provided, e.g. \code{lon = c(0:50, 300:360)} +#' ('var' must be provided consitently). +#'@param lat Numeric vector of latitude locations of the cell centers of the +#' grid of 'var', in any order (same as 'var'). Expected to be from a regular +#' rectangular or gaussian grid, within the range [-90, 90]. +#'@param latlims Latitudinal limits of the figure.\cr +#' Example : c(60, 90) for the North Pole\cr +#' c(-90,-60) for the South Pole +#'@param toptitle Top title of the figure, scalable with parameter +#' 'title_scale'. +#'@param sizetit Scale factor for the figure top title provided in parameter +#' 'toptitle'. Deprecated. Use 'title_scale' instead. +#'@param units Title at the top of the colour bar, most commonly the units of +#' the variable provided in parameter 'var'. +#'@param brks,cols,bar_limits,triangle_ends Usually only providing 'brks' is +#' enough to generate the desired colour bar. These parameters allow to +#' define n breaks that define n - 1 intervals to classify each of the values +#' in 'var'. The corresponding grid cell of a given value in 'var' will be +#' coloured in function of the interval it belongs to. These parameters are +#' sent to \code{ColorBar()} to generate the breaks and colours. Additional +#' colours for values beyond the limits of the colour bar are also generated +#' and applied to the plot if 'bar_limits' or 'brks' and 'triangle_ends' are +#' properly provided to do so. See ?ColorBar for a full explanation. +#'@param col_inf,col_sup,colNA Colour identifiers to colour the values in +#' 'var' that go beyond the extremes of the colour bar and to colour NA +#' values, respectively. 'colNA' takes attr(cols, 'na_color') if available by +#' default, where cols is the parameter 'cols' if provided or the vector of +#' colors returned by 'color_fun'. If not available, it takes 'pink' by +#' default. 'col_inf' and 'col_sup' will take the value of 'colNA' if not +#' specified. See ?ColorBar for a full explanation on 'col_inf' and 'col_sup'. +#'@param color_fun,subsampleg,bar_extra_labels,draw_bar_ticks,draw_separators,triangle_ends_scale,bar_label_digits,bar_label_scale,units_scale,bar_tick_scale,bar_extra_margin Set of parameters to control the visual +#' aspect of the drawn colour bar. See ?ColorBar for a full explanation. +#'@param filled.continents Colour to fill in drawn projected continents. Takes +#' the value gray(0.5) by default. If set to FALSE, continents are not +#' filled in. +#'@param coast_color Colour of the coast line of the drawn projected +#' continents. Takes the value gray(0.5) by default. +#'@param coast_width Line width of the coast line of the drawn projected +#' continents. Takes the value 1 by default. +#'@param dots Array of same dimensions as 'var' or with dimensions +#' c(n, dim(var)), where n is the number of dot/symbol layers to add to the +#' plot. A value of TRUE at a grid cell will draw a dot/symbol on the +#' corresponding square of the plot. By default all layers provided in 'dots' +#' are plotted with dots, but a symbol can be specified for each of the +#' layers via the parameter 'dot_symbol'. +#'@param dot_symbol Single character/number or vector of characters/numbers +#' that correspond to each of the symbol layers specified in parameter 'dots'. +#' If a single value is specified, it will be applied to all the layers in +#' 'dots'. Takes 15 (centered square) by default. See 'pch' in par() for +#' additional accepted options. +#'@param dot_size Scale factor for the dots/symbols to be plotted, specified +#' in 'dots'. If a single value is specified, it will be applied to all +#' layers in 'dots'. Takes 1 by default. +#'@param intlat Interval between latitude lines (circles), in degrees. +#' Defaults to 10. +#'@param drawleg Whether to plot a color bar (legend, key) or not. +#' Defaults to TRUE. +#'@param boxlim Limits of a box to be added to the plot, in degrees: +#' c(x1, y1, x2, y2). A list with multiple box specifications can also +#' be provided. +#'@param boxcol Colour of the box lines. A vector with a colour for each of +#' the boxes is also accepted. Defaults to 'purple2'. +#'@param boxlwd Line width of the box lines. A vector with a line width for +#' each of the boxes is also accepted. Defaults to 5. +#'@param margin_scale Scale factor for the margins to be added to the plot, +#' with the format c(y1, x1, y2, x2). Defaults to rep(1, 4). If drawleg = TRUE, +#' margin_scale[1] is subtracted 1 unit. +#'@param title_scale Scale factor for the figure top title. Defaults to 1. +#'@param numbfig Number of figures in the layout the plot will be put into. +#' A higher numbfig will result in narrower margins and smaller labels, +#' axe labels, ticks, thinner lines, ... Defaults to 1. +#'@param fileout File where to save the plot. If not specified (default) a +#' graphics device will pop up. Extensions allowed: eps/ps, jpeg, png, pdf, +#' bmp and tiff. +#'@param width File width, in the units specified in the parameter size_units +#' (inches by default). Takes 8 by default. +#'@param height File height, in the units specified in the parameter +#' size_units (inches by default). Takes 5 by default. +#'@param size_units Units of the size of the device (file or window) to plot +#' in. Inches ('in') by default. See ?Devices and the creator function of +#' the corresponding device. +#'@param res Resolution of the device (file or window) to plot in. See +#' ?Devices and the creator function of the corresponding device. +#'@param \dots Arguments to be passed to the method. Only accepts the +#' following graphical parameters:\cr +#' adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt +#' csi cxy err family fg font font.axis font.lab font.main font.sub lend +#' lheight ljoin lmitre mex mfcol mfrow mfg mkh omd omi page pch pin plt pty +#' smo srt tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog \cr +#' For more information about the parameters see `par`. +#' +#'@return +#'\item{brks}{ +#' Breaks used for colouring the map (and legend if drawleg = TRUE). +#'} +#'\item{cols}{ +#' Colours used for colouring the map (and legend if drawleg = TRUE). Always +#' of length length(brks) - 1. +#'} +#'\item{col_inf}{ +#' Colour used to draw the lower triangle end in the colour bar (NULL if not +#' drawn at all). +#'} +#'\item{col_sup}{ +#' Colour used to draw the upper triangle end in the colour bar (NULL if not +#' drawn at all). +#'} +#' +#'@keywords dynamic +#'@author History:\cr +#'1.0 - 2014-07 (V. Guemas, \email{virginie.guemas@@ic3.cat}) - Original code\cr +#'1.1 - 2015-12 (C. Ardilouze, \email{constantin.ardilouze@@meteo.fr}) - Box(es) drawing\cr +#'1.2 - 2016-08 (N. Manubens, \email{nicolau.manubens@@bsc.es}) - Refacotred the function and +#' merged in Jean-Philippe circle +#' border and Constantin boxes. +#'@examples +#'data <- matrix(rnorm(100 * 50), 100, 50) +#'x <- seq(from = 0, to = 360, length.out = 100) +#'y <- seq(from = -90, to = 90, length.out = 50) +#'PlotStereoMap(data, x, y, latlims = c(60, 90), brks = 50, +#' toptitle = "This is the title") +#'@import mapproj +#'@importFrom grDevices dev.cur dev.new dev.off gray +#'@importFrom stats median +#'@export PlotStereoMap <- function(var, lon, lat, latlims = c(60, 90), toptitle = NULL, sizetit = NULL, units = NULL, brks = NULL, cols = NULL, bar_limits = NULL, diff --git a/R/PlotVsLTime.R b/R/PlotVsLTime.R index ff7a37c1c7c85de5613616b10731ef88f7965246..e3f7b7f758fc9a82f661fdbcae4927084e3b994e 100644 --- a/R/PlotVsLTime.R +++ b/R/PlotVsLTime.R @@ -1,3 +1,103 @@ +#'Plots A Score Along The Forecast Time With Its Confidence Interval +#' +#'Plots The Correlation (\code{Corr()}) or the Root Mean Square Error +#'(\code{RMS()}) between the forecasted values and their observational +#'counterpart or the slopes of their trends (\code{Trend()}) or the +#'InterQuartile Range, Maximum-Mininum, Standard Deviation or Median Absolute +#'Deviation of the Ensemble Members (\code{Spread()}), or the ratio between +#'the Ensemble Spread and the RMSE of the Ensemble Mean (\code{RatioSDRMS()}) +#'along the forecast time for all the input experiments on the same figure +#'with their confidence intervals. +#' +#'@param var Matrix containing any Prediction Score with dimensions:\cr +#' (nexp/nmod, 3/4 ,nltime)\cr +#' or (nexp/nmod, nobs, 3/4 ,nltime). +#'@param toptitle Main title, optional. +#'@param ytitle Title of Y-axis, optional. +#'@param monini Starting month between 1 and 12. Default = 1. +#'@param freq 1 = yearly, 12 = monthly, 4 = seasonal, ... Default = 12. +#'@param nticks Number of ticks and labels on the x-axis, optional. +#'@param limits c(lower limit, upper limit): limits of the Y-axis, optional. +#'@param listexp List of experiment names, optional. +#'@param listobs List of observation names, optional. +#'@param biglab TRUE/FALSE for presentation/paper plot. Default = FALSE. +#'@param hlines c(a,b, ..) Add horizontal black lines at Y-positions a,b, ...\cr +#' Default = NULL. +#'@param leg TRUE/FALSE if legend should be added or not to the plot. +#' Default = TRUE. +#'@param siglev TRUE/FALSE if significance level should replace confidence +#' interval.\cr +#' Default = FALSE. +#'@param sizetit Multiplicative factor to change title size, optional. +#'@param show_conf TRUE/FALSE to show/not confidence intervals for input +#' variables. +#'@param fileout Name of output file. Extensions allowed: eps/ps, jpeg, png, +#' pdf, bmp and tiff.\cr +#' Default = 'output_plotvsltime.eps' +#'@param width File width, in the units specified in the parameter size_units +#' (inches by default). Takes 8 by default. +#'@param height File height, in the units specified in the parameter +#' size_units (inches by default). Takes 5 by default. +#'@param size_units Units of the size of the device (file or window) to plot +#' in. Inches ('in') by default. See ?Devices and the creator function of the +#' corresponding device. +#'@param res Resolution of the device (file or window) to plot in. See +#' ?Devices and the creator function of the corresponding device. +#'@param ... Arguments to be passed to the method. Only accepts the following +#' graphical parameters:\cr +#' adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt +#' csi cxy err family fg fig font font.axis font.lab font.main font.sub +#' lheight ljoin lmitre mar mex mfcol mfrow mfg mkh oma omd omi page pch plt +#' smo srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog \cr +#' For more information about the parameters see `par`. +#' +#'@details +#'Examples of input:\cr +#'Model and observed output from \code{Load()} then \code{Clim()} then +#'\code{Ano()} then \code{Smoothing()}:\cr +#'(nmod, nmemb, nsdate, nltime) and (nobs, nmemb, nsdate, nltime)\cr +#'then averaged over the members\cr +#'\code{Mean1Dim(var_exp/var_obs, posdim = 2)}:\cr +#'(nmod, nsdate, nltime) and (nobs, nsdate, nltime)\cr +#'then passed through\cr +#' \code{Corr(exp, obs, posloop = 1, poscor = 2)} or\cr +#' \code{RMS(exp, obs, posloop = 1, posRMS = 2)}:\cr +#' (nmod, nobs, 3, nltime)\cr +#'would plot the correlations or RMS between each exp & each obs as a function +#'of the forecast time. +#' +#'@keywords dynamic +#'@author History:\cr +#'0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@@ic3.cat}) - Original code\cr +#'0.2 - 2013-03 (I. Andreu-Burillo, \email{isabel.andreu-burillo@@ic3.cat}) - Introduced parameter sizetit\cr +#'0.3 - 2013-10 (I. Andreu-Burillo, \email{isabel.andreu-burillo@@ic3.cat}) - Introduced parameter show_conf\cr +#'1.0 - 2013-11 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to CRAN +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'ano_exp <- Ano(sampleData$mod, clim$clim_exp) +#'ano_obs <- Ano(sampleData$obs, clim$clim_obs) +#'runmean_months <- 12 +#'dim_to_smooth <- 4 # Smooth along lead-times +#'smooth_ano_exp <- Smoothing(ano_exp, runmean_months, dim_to_smooth) +#'smooth_ano_obs <- Smoothing(ano_obs, runmean_months, dim_to_smooth) +#'dim_to_mean <- 2 # Mean along members +#'required_complete_row <- 3 # Discard startdates for which there are NA leadtimes +#'leadtimes_per_startdate <- 60 +#'corr <- Corr(Mean1Dim(smooth_ano_exp, dim_to_mean), +#' Mean1Dim(smooth_ano_obs, dim_to_mean), +#' compROW = required_complete_row, +#' limits = c(ceiling((runmean_months + 1) / 2), +#' leadtimes_per_startdate - floor(runmean_months / 2))) +#'PlotVsLTime(corr, toptitle = "correlations", ytitle = "correlation", +#' monini = 11, limits = c(-1, 2), listexp = c('CMIP5 IC3'), +#' listobs = c('ERSST'), biglab = FALSE, hlines = c(-1, 0, 1), +#' fileout = 'tos_cor.eps') +#' +#'@importFrom grDevices dev.cur dev.new dev.off +#'@importFrom stats ts +#'@export PlotVsLTime <- function(var, toptitle = '', ytitle = '', monini = 1, freq = 12, nticks = NULL, limits = NULL, listexp = c('exp1', 'exp2', 'exp3'), diff --git a/R/ProbBins.R b/R/ProbBins.R index fef21045aa5f71b807852442f8316e85c0aa314e..e49c27b5585264307650074831f6182691240e5b 100644 --- a/R/ProbBins.R +++ b/R/ProbBins.R @@ -1,3 +1,73 @@ +#'Computes Probabilistic Information of a Forecast Relative to a Threshold or a Quantile +#' +#'Compute probabilistic bins of a set of forecast years ('fcyr') relative to +#'the forecast climatology over the whole period of anomalies, optionally excluding +#'the selected forecast years ('fcyr') or the forecast year for which the +#'probabilistic bins are being computed (see 'compPeriod'). +#' +#'@param ano Array of anomalies from Ano().\cr +#' Must be of dimension (nexp/nobs, nmemb, nsdates, nleadtime, nlat, nlon) +#'@param fcyr Indices of the forecast years of the anomalies which to compute +#' the probabilistic bins for, or 'all' to compute the bins for all the +#' years.\cr +#' E.g., c(1:5), c(1, 4), 4 or 'all'. +#'@param thr Values used as thresholds to bin the anomalies. +#'@param quantile If quantile is TRUE (default), the threshold ('thr') +#' are quantiles.\cr +#' If quantile is FALSE the thresholds ('thr') introduced are the absolute +#' thresholds of the bins. +#'@param posdates Position of the dimension in \code{ano} that corresponds to +#' the start dates (default = 3). +#'@param posdim Position of the dimension in \code{ano} which will be combined +#' with 'posdates' to compute the quantiles (default = 2, ensemble members). +#'@param compPeriod Three options: +#' "Full period"/"Without fcyr"/"Cross-validation" (The probabilities are +#' computed with the terciles based on ano/ano with all 'fcyr's +#' removed/cross-validation). The default is "Full period". +#' +#'@return Array with probabilistic information and dimensions:\cr +#' c(length('thr') + 1, length(fcyr), nmemb/nparam, nmod/nexp/nobs, +#' nltime, nlat, nlon)\cr +#' The values along the first dimension take values 0 or 1 depending on which +#' of the 'thr'+1 cathegories the forecast/observation at the corresponding +#' grid point, time step, member and starting date belongs to. +#' +#'@keywords datagen +#'@author History:\cr +#'1.0 - 2013 (F.Lienert) - Original code\cr +#'2.0 - 2014-03 (N. Gonzalez and V. Torralba, \email{veronica.torralba@@bsc.es}) - Debugging +#'2.1 - 2017-02 (V. Torralba and N. Manubens, \email{veronica.torralba@@bsc.es}) - Fix bug with cross-validation +#'@examples +#'# See examples on Load() to understand the first lines in this example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' output = 'lonlat', latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'clim <- Clim(sampleMap$mod, sampleMap$obs) +#'ano_exp <- Ano(sampleMap$mod, clim$clim_exp) +#'PB <- ProbBins(ano_exp, fcyr = 3, thr = c(1/3, 2/3), quantile = TRUE, posdates = 3, +#' posdim = 2) +#' +#'@export ProbBins <- function(ano, fcyr = 'all', thr, quantile = TRUE, posdates = 3, posdim = 2, compPeriod = "Full period") { # define dimensions diff --git a/R/ProjectField.R b/R/ProjectField.R index d88fe3550354163a6880279055557f7f2f8a069b..07d890f61d00fff7f56792087b57274f341fbc55 100644 --- a/R/ProjectField.R +++ b/R/ProjectField.R @@ -1,3 +1,100 @@ +#'Project Anomalies onto Modes of Variability +#' +#'Project anomalies onto modes of variability to get the temporal evolution of +#'the EOF mode selected. Returns principal components (PCs) by +#'area-weighted projection onto EOF pattern (from \code{EOF()}). +#'Able to handle NAs. +#' +#'@param ano Array of forecast or observational reference anomalies from +#' \code{Ano()} or \code{Ano_CrossValid} with dimensions (number of forecast +#' systems, ensemble members, start dates, forecast horizons, latitudes, +#' longitudes). +#'@param eof R object with EOFs from \code{EOF}. +#'@param mode Variability mode number in the provided EOF object which to +#' project onto. +#' +#'@return Array of principal components in verification format (number of +#' forecast systems, ensemble members, start dates, forecast horizons). +#' +#'@keywords datagen +#'@seealso EOF, NAO, PlotBoxWhisker +#'@author History:\cr +#'0.1 - 2012-03 (F. Lienert, \email{flienert@ic3.cat} - Original code\cr +#'0.2 - 2014-03 (Lauriane Batte, \email{lauriane.batte@ic3.cat} - Bug-fixes:\cr +#' 1- Extra weighting of the anomalies before projection.\cr +#' 2- Reversion of the anomalies along latitudes.\cr +#' 3- Extra-normalisation not necessary.\cr +#'0.3 - 2014-03 (Virginie Guemas, \email{virginie.guemas@bsc.es} - Bug-fixes:\cr +#' 1- Another extra-normalisation.\cr +#' 2- 15 lines to compute the em reduced to 1. +#'0.4 - 2014-03 (Lauriane Batte, \email{lauriane.batte@ic3.cat} - Normalization\cr +#'by std before returning PCs to be coherent with EOF().\cr +#'0.5 - 2014-04 (Virginie Guemas, \email{virginie.guemas@bsc.es} - Fixes:\cr +#' 1- Removal of lon, lat, ncpu and neofs argument unused\cr +#' 2- Security checks ano and eof consistency\cr +#' 3- Removal of the mask which is already contained in the EOFs\cr +#' 4- Removal of the PC normalization since we have chosen in\cr +#'\code{EOF()} to normalize the EOFs and multiply the PCs by the normalization\cr +#'factor and the eigenvalue so that the restitution of the original field is \cr +#'done simply by PC * EOFs\cr +#' 5 - The new convention in \code{EOF()} is to divide by the weights\cr +#'so that the reconstruction of the original field rather than the weighted\cr +#'field is obtained by PC * EOFs. The EOFs need therefore to be multiplied \cr +#'back by the weights before projection so that EOF * t(EOF) = 1\cr +#' 6 - Since W *X = PC * EOF if EOF is multiplied back by the weights,\cr +#'PC = W * X * t(EOF) and X the input field to be projected (X) needs to be\cr +#'multiplied by W. Getting input dimensions. +#'1.0 - 2016-03 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Formatting to R CRAN\cr +#' (J.-P. Baudouin, \email{jean.baudouin@bsc.es}) - Example code and testing +#' +#'@examples +#'# See examples on Load() to understand the first lines in this example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' leadtimemin = 1, leadtimemax = 4, output = 'lonlat', +#' latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' leadtimemin = 1, +#' leadtimemax = 4, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'# Now ready to compute the EOFs and project. +#'ano <- Ano_CrossValid(sampleData$mod, sampleData$obs) +#' +#'# Compute the EOF of the observation. +#'eof <- EOF(ano$ano_obs[1, 1, , 1, , ], sampleData$lon, sampleData$lat) +#'# check the first mode represent the NAO +#'PlotEquiMap(eof$EOFs[1, , ], sampleData$lon, sampleData$lat, filled.continents = FALSE) +#' +#'mode1_exp <- ProjectField(ano$ano_exp, eof, 1) +#'mode1_obs <- ProjectField(ano$ano_obs, eof, 1) +#' +#'# Plot the forecast and the observation of the first mode +#'# for the last year of forecast +#'plot(mode1_obs[1, 1, dim(sampleData$mod)[3], ], type = "l", ylim = c(-1, 1), lwd = 2) +#'for (i in 1:dim(sampleData$mod)[2]) { +#' par(new = TRUE) +#' plot(mode1_exp[1, i, dim(sampleData$mod)[3], ], type = "l", col = rainbow(10)[i], +#' ylim = c(-15000, 15000)) +#'} +#' +#'@export ProjectField <- function(ano, eof, mode = 1) { # Checking ano if (!is.numeric(ano) || !is.array(ano)) { diff --git a/R/RMS.R b/R/RMS.R index b45f8cab0f8813b8f3499348bac2b5d02a6b9a08..bb3dd3890a800a3a0ec0f3c132a6b66998a0791a 100644 --- a/R/RMS.R +++ b/R/RMS.R @@ -1,3 +1,100 @@ +#'Computes Root Mean Square Error +#' +#'Computes the root mean square error for an array of forecasts, var_exp and +#'an array of observations, var_obs, which should have the same dimensions +#'except along the posloop dimension where the lengths can be different, with +#'the number of experiments/models for var_exp (nexp) and the number of +#'obserational datasets for var_obs (nobs).\cr +#'The RMSE is computed along the posRMS dimension which should correspond to +#'the startdate dimension.\cr +#'If compROW is given, the RMSE is computed only if rows along the compROW +#'dimension are complete between limits[1] and limits[2], i.e. there are no +#'NAs between limits[1] and limits[2]. This option can be activated if the +#'user wishes to account only for the forecasts for which observations are +#'available at all leadtimes.\cr +#'Default: limits[1] = 1 and limits[2] = length(compROW dimension).\cr +#'The confidence interval relies on a chi2 distribution.\cr\cr +#'.RMS provides the same functionality but taking a matrix of ensemble +#'members as input (exp). +#' +#'@param var_exp Matrix of experimental data. +#'@param var_obs Matrix of observational data, same dimensions as var_exp +#' except along posloop dimension, where the length can be nobs instead of +#' nexp. +#'@param posloop Dimension nobs and nexp. +#'@param posRMS Dimension along which RMSE are to be computed (the dimension +#' of the start dates). +#'@param compROW Data taken into account only if (compROW)th row is complete.\cr +#' Default = NULL. +#'@param limits Complete between limits[1] & limits[2]. Default = NULL. +#'@param siglev Confidence level of the computed confidence interval. 0.95 +#' by default. +#'@param conf Whether to compute confidence interval or not. TRUE by default. +#'@param exp N by M matrix of N forecasts from M ensemble members. +#'@param obs Vector of the corresponding observations of length N. +#' +#'@return +#'RMS: Array with dimensions:\cr +#'c(length(posloop) in var_exp, length(posloop) in var_obs, 1 or 3, all +#' other dimensions of var_exp & var_obs except posRMS).\cr +#'The 3rd dimension corresponds to the lower limit of the 95\% confidence +#' interval (only present if \code{conf = TRUE}), the RMSE, and the upper +#' limit of the 95\% confidence interval (only present if +#' \code{conf = TRUE}).\cr\cr +#'.RMS: +#'\item{$rms}{ +#'The root mean square error, +#'} +#'\item{$conf_low}{ +#' Corresponding to the lower limit of the \code{siglev}\% confidence interval +#' (only present if \code{conf = TRUE}) for the rms. +#'} +#'\item{$conf_high}{ +#' Corresponding to the upper limit of the \code{siglev}\% confidence interval +#' (only present if \code{conf = TRUE}) for the rms. +#'} +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2011-05 (V. Guemas, \email{vguemas@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens2@ic3.cat}) - Formatting to R CRAN\cr +#'1.1 - 2017-02 (A. Hunter, \email{alasdair.hunter@bsc.es}) - Adapted to veriApply() +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'ano_exp <- Ano(sampleData$mod, clim$clim_exp) +#'ano_obs <- Ano(sampleData$obs, clim$clim_obs) +#'runmean_months <- 12 +#'dim_to_smooth <- 4 # Smooth along lead-times +#'smooth_ano_exp <- Smoothing(ano_exp, runmean_months, dim_to_smooth) +#'smooth_ano_obs <- Smoothing(ano_obs, runmean_months, dim_to_smooth) +#'dim_to_mean <- 2 # Mean along members +#'# Discard start-dates for which some leadtimes are missing +#'required_complete_row <- 3 +#'leadtimes_per_startdate <- 60 +#'rms <- RMS(Mean1Dim(smooth_ano_exp, dim_to_mean), +#' Mean1Dim(smooth_ano_obs, dim_to_mean), +#' compROW = required_complete_row, +#' limits = c(ceiling((runmean_months + 1) / 2), +#' leadtimes_per_startdate - floor(runmean_months / 2))) +#'PlotVsLTime(rms, toptitle = "Root Mean Square Error", ytitle = "K", +#' monini = 11, limits = NULL, listexp = c('CMIP5 IC3'), +#' listobs = c('ERSST'), biglab = FALSE, hlines = c(0), +#' fileout = 'tos_rms.eps') +#'# The following example uses veriApply combined with .RMS instead of RMS +#' \dontrun{ +#'require(easyVerification) +#'RMS2 <- s2dverification:::.RMS +#'rms2 <- veriApply("RMS2", +#' smooth_ano_exp, +#' # see ?veriApply for how to use the 'parallel' option +#' Mean1Dim(smooth_ano_obs, dim_to_mean), +#' tdim = 3, ensdim = 2) +#' } +#' +#'@rdname RMS +#'@export RMS <- function(var_exp, var_obs, posloop = 1, posRMS = 2, compROW = NULL, limits = NULL, siglev = 0.95, conf = TRUE) { # @@ -100,7 +197,9 @@ RMS <- function(var_exp, var_obs, posloop = 1, posRMS = 2, compROW = NULL, # enlrms } - +#'@rdname RMS +#'@importFrom stats qchisq +#'@export .RMS <- function(exp, obs, siglev = 0.95, conf = TRUE) { # # RMS & its confidence interval computation diff --git a/R/RMSSS.R b/R/RMSSS.R index 42622477f39ab291b4c179ec9799dacc1e94787f..16623b3262762ccab1673a296e57601d5d0ed7a0 100644 --- a/R/RMSSS.R +++ b/R/RMSSS.R @@ -1,3 +1,76 @@ +#'Computes Root Mean Square Skill Score +#' +#'Computes the root mean square error skill score between an array of +#'forecasts, var_exp and an array of observations, var_obs, which should +#'have the same dimensions except along posloop where the lengths can be +#'different, with the number of experiments/models for var_exp (nexp) and +#'the number of obserational datasets for var_obs (nobs).\cr +#'RMSSS computes the Root Mean Square Skill Score of each jexp in 1:nexp +#'against each jobs in 1:nobs which gives nexp x nobs RMSSS for each other +#'grid point of the matrix (each latitude/longitude/level/leadtime).\cr +#'The RMSSS are computed along the posRMS dimension which should correspond +#'to the startdate dimension.\cr +#'The p-value is optionally provided by a one-sided Fisher test.\cr\cr +#'.RMSSS provides the same functionality but taking a matrix of ensemble +#'members as input (exp). +#' +#'@param var_exp Array of experimental data. +#'@param var_obs Array of observational data, same dimensions as var_exp +#' except along posloop dimension, where the length can be nobs instead of +#' nexp. +#'@param posloop Dimension nobs and nexp. +#'@param posRMS Dimension along which the RMSE are to be computed (the +#' dimension of the start dates). +#'@param pval Whether to compute or not the p-value of the test Ho : +#' RMSSS = 0. TRUE by default. +#'@param exp N by M matrix of N forecasts from M ensemble members. +#'@param obs Vector of the corresponding observations of length N. +#' +#'@return RMSSS: Array with dimensions:\cr +#' c(length(posloop) in var_exp, length(posloop) in var_obs, 1 or 2, +#' all other dimensions of var_exp & var_obs except posRMS).\cr +#'The 3rd dimension corresponds to the RMSSS and, if \code{pval = TRUE}, +#' the p-value of the one-sided Fisher test with Ho: RMSSS = 0.\cr\cr +#'.RMSSS: +#' \itemize{ +#' \item{$rmsss}{ +#' The RMSSS. +#' } +#' \item{$p_val}{ +#' Corresponds to the p values (only present if \code{pval = TRUE}) for +#' the RMSSS. +#' } +#' } +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2012-04 (V. Guemas, \email{vguemas@@bsc.es}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@bsc.es}) - Formatting to R CRAN\cr +#'1.1 - 2017-02 (A. Hunter, \email{alasdair.hunter@@bsc.es}) - Adapted to veriApply() +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'ano_exp <- Ano(sampleData$mod, clim$clim_exp) +#'ano_obs <- Ano(sampleData$obs, clim$clim_obs) +#'rmsss <- RMSSS(Mean1Dim(ano_exp, 2), Mean1Dim(ano_obs, 2)) +#'rmsss_plot <- array(dim = c(dim(rmsss)[1:2], 4, dim(rmsss)[4])) +#'rmsss_plot[, , 2, ] <- rmsss[, , 1, ] +#'rmsss_plot[, , 4, ] <- rmsss[, , 2, ] +#'PlotVsLTime(rmsss_plot, toptitle = "Root Mean Square Skill Score", ytitle = "", +#' monini = 11, limits = c(-1, 1.3), listexp = c('CMIP5 IC3'), +#' listobs = c('ERSST'), biglab = FALSE, hlines = c(-1, 0, 1), +#' fileout = 'tos_rmsss.eps') +#'# The following example uses veriApply combined with .RMSSS instead of RMSSS +#' \dontrun{ +#'require(easyVerification) +#'RMSSS2 <- s2dverification:::.RMSSS +#'rmsss2 <- veriApply("RMSSS2", ano_exp, +#' # see ?veriApply for how to use the 'parallel' option +#' Mean1Dim(ano_obs, 2), +#' tdim = 3, ensdim = 2) +#' } +#'@rdname RMSSS +#'@export RMSSS <- function(var_exp, var_obs, posloop = 1, posRMS = 2, pval = TRUE) { # # Enlarge var_exp & var_obs & clim to 10 dim + move posloop & posRMS @@ -87,7 +160,9 @@ RMSSS <- function(var_exp, var_obs, posloop = 1, posRMS = 2, pval = TRUE) { # enlRMSSS } - +#'@rdname RMSSS +#'@importFrom stats pf +#'@export .RMSSS <- function(exp, obs, pval = TRUE) { dif2 <- obs dif1 <- rowMeans(exp) - obs diff --git a/R/RatioRMS.R b/R/RatioRMS.R index 564f9658d5f2a1566372d8b9d98ca56fe13ac7b5..9ac39041daef12d8befc789967f84c1ebbcffc39 100644 --- a/R/RatioRMS.R +++ b/R/RatioRMS.R @@ -1,3 +1,106 @@ +#'Computes the Ratio Between The RMSE of Two Experiments +#' +#'Calculates the ratio of the RMSE for two forecasts of the same observations.\cr +#'The ratio RMSE(ens, obs) / RMSE(ens.ref, obs) is output.\cr +#'The p-value is provided by a two-sided Fischer test.\cr\cr +#'.RatioRMS provides the same functionality but taking two matrices of +#'ensemble members (ens and ens.ref) as input. +#' +#'@param var_exp1 Array of experimental data 1. +#'@param var_exp2 Array of experimental data 2. +#'@param var_obs Array of observations. +#'@param posRMS Dimension along which the RMSE are to be computed = the +#' position of the start dates. +#'@param pval Whether to compute the p-value of Ho : RMSE1/RMSE2 = 1 or not. +#' TRUE by default. +#'@param exp Matrix of experimental data 1. +#'@param exp_ref Matrix of experimental data 2. +#'@param obs Vector of observations. +#' +#'@return RatioRMS:\cr +#'Matrix with the same dimensions as var_exp1/var_exp2/var_obs except along +#' posRMS where the dimension has length 2 if 'pval = TRUE', or 1 otherwise. +#' The dimension of length 2 corresponds to the ratio between the RMSE +#' (RMSE1/RMSE2) and the p-value of the two-sided Fisher test with Ho: +#' RMSE1/RMSE2 = 1.\cr\cr +#'.RatioRMS:\cr +#' \itemize{ +#' \item{ratiorms}{The ratio of the RMSE of the two experimental datasets} +#' \item{p_val}{The p-value} +#' } +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2011-11 (V. Guemas, \email{vguemas@bsc.es}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Formatting to R CRAN\cr +#'1.1 - 2017-02 (A. Hunter, \email{alasdair.hunter@bsc.es}) - Adapted to veriApply() +#'@examples +#'# See examples on Load() to understand the first lines in this example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' output = 'lonlat', latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'# Compute DJF seasonal means and anomalies. +#'leadtimes_dimension <- 4 +#'initial_month <- 11 +#'mean_start_month <- 12 +#'mean_stop_month <- 2 +#'sampleData$mod <- Season(sampleData$mod, leadtimes_dimension, initial_month, +#' mean_start_month, mean_stop_month) +#'sampleData$obs <- Season(sampleData$obs, leadtimes_dimension, initial_month, +#' mean_start_month, mean_stop_month) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'ano_exp <- Ano(sampleData$mod, clim$clim_exp) +#'ano_obs <- Ano(sampleData$obs, clim$clim_obs) +#'# Generate two experiments with 2 and 1 members from the only experiment +#'# available in the sample data. Take only data values for a single forecast +#'# time step. +#'ano_exp_1 <- Subset(ano_exp, 'member', c(1, 2)) +#'ano_exp_2 <- Subset(ano_exp, 'member', c(3)) +#'ano_exp_1 <- Subset(ano_exp_1, c('dataset', 'ftime'), list(1, 1), drop = 'selected') +#'ano_exp_2 <- Subset(ano_exp_2, c('dataset', 'ftime'), list(1, 1), drop = 'selected') +#'ano_obs <- Subset(ano_obs, c('dataset', 'ftime'), list(1, 1), drop = 'selected') +#'# Compute ensemble mean and provide as inputs to RatioRMS. +#'rrms <- RatioRMS(Mean1Dim(ano_exp_1, 1), +#' Mean1Dim(ano_exp_2, 1), +#' Mean1Dim(ano_obs, 1)) +#'# Plot the RatioRMS for the first forecast time step. +#'PlotEquiMap(rrms[1, , ], sampleData$lon, sampleData$lat, +#' toptitle = 'Ratio RMSE') +#' +#'# The following example uses veriApply combined with .RatioRMS instead of RatioRMS +#' \dontrun{ +#'require(easyVerification) +#'# The name of the function has to end in 'ss' in order for veriApply() to +#'# detect it as a skill score. +#'RatioRMSss <- s2dverification:::.RatioRMS +#'rrms2 <- veriApply("RatioRMSss", ano_exp_1, +#' # see ?veriApply for how to use the 'parallel' option +#' Mean1Dim(ano_obs, 1), +#' ano_exp_2, +#' tdim = 2, ensdim = 1) +#' } +#'@rdname RatioRMS +#'@export RatioRMS <- function(var_exp1, var_exp2, var_obs, posRMS = 1, pval = TRUE) { # # Enlarge var_exps & var_obs to 10 dim + move posRMS to 1st pos @@ -84,7 +187,8 @@ RatioRMS <- function(var_exp1, var_exp2, var_obs, posRMS = 1, pval = TRUE) { # enlratiorms } - +#'@rdname RatioRMS +#'@export .RatioRMS <- function(exp, exp_ref, obs, pval = TRUE) { # # RMS ratio and its pvalue computation diff --git a/R/RatioSDRMS.R b/R/RatioSDRMS.R index 2bce490dda043a35b3dfc5fd7a9a6308f63873e0..ec16bc3b43483ef891c08c98181360047b5ea33e 100644 --- a/R/RatioSDRMS.R +++ b/R/RatioSDRMS.R @@ -1,3 +1,72 @@ +#'Computes the ratio between the ensemble spread and RMSE +#' +#'Arrays var_exp & var_obs should have dimensions between\cr +#'c(nmod/nexp, nmemb/nparam, nsdates, nltime)\cr +#'and\cr +#'c(nmod/nexp, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon)\cr +#'The ratio between the standard deviation of the members around the ensemble +#'mean in var_exp and the RMSE between var_exp and var_obs is output for each +#'experiment and each observational dataset.\cr +#'The p-value is provided by a one-sided Fischer test.\cr\cr +#'.RatioSDRMS provides the same functionality but taking a matrix of ensemble +#'members as input (exp). +#' +#'@param var_exp Model data:\cr +#' c(nmod/nexp, nmemb/nparam, nsdates, nltime) up to\cr +#' c(nmod/nexp, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon) +#'@param var_obs Observational data:\cr +#' c(nobs, nmemb, nsdates, nltime) up to\cr +#' c(nobs, nmemb, nsdates, nltime, nlevel, nlat, nlon) +#'@param pval Whether to compute the p-value of Ho : SD/RMSE = 1 or not. +#'@param exp N by M matrix of N forecasts from M ensemble members. +#'@param obs Vector of the corresponding observations of length N. +#' +#'@return RatioSDRMS: Array with dimensions c(nexp/nmod, nobs, 1 or 2, nltime) +#' up to c(nexp/nmod, nobs, 1 or 2, nltime, nlevel, nlat, nlon).\cr +#'The 3rd dimension corresponds to the ratio (SD/RMSE) and the p.value +#' (only present if \code{pval = TRUE}) of the one-sided Fisher test with +#'Ho: SD/RMSE = 1.\cr\cr +#'.RatioSDRMS: +#' \itemize{ +#' \item{$ratio}{ +#' The ratio of the ensemble spread and RMSE, +#' } +#' \item{$p_val}{ +#' Corresponds to the p values of the ratio (only present if +#' \code{pval = TRUE}). +#' } +#' } +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2011-12 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau-manubens@ic3.cat}) - Formatting to CRAN\cr +#'1.1 - 2017-02 (A. Hunter, \email{alasdair.hunter@bsc.es}) - Adapted to veriApply() +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'rsdrms <- RatioSDRMS(sampleData$mod, sampleData$obs) +#'# Reorder the data in order to plot it with PlotVsLTime +#'rsdrms_plot <- array(dim = c(dim(rsdrms)[1:2], 4, dim(rsdrms)[4])) +#'rsdrms_plot[, , 2, ] <- rsdrms[, , 1, ] +#'rsdrms_plot[, , 4, ] <- rsdrms[, , 2, ] +#'PlotVsLTime(rsdrms_plot, toptitle = "Ratio ensemble spread / RMSE", ytitle = "", +#' monini = 11, limits = c(-1, 1.3), listexp = c('CMIP5 IC3'), +#' listobs = c('ERSST'), biglab = FALSE, siglev = TRUE, +#' fileout = 'tos_rsdrms.eps') +#' +#'# The following example uses veriApply combined with .RatioSDRMS instead of RatioSDRMS +#' \dontrun{ +#'require(easyVerification) +#'RatioSDRMS2 <- s2dverification:::.RatioSDRMS +#'rsdrms2 <- veriApply("RatioSDRMS2", +#' sampleData$mod, +#' # see ?veriApply for how to use the 'parallel' option +#' Mean1Dim(sampleData$obs, 2), +#' tdim = 3, ensdim = 2) +#' } +#'@rdname RatioSDRMS +#'@export RatioSDRMS <- function(var_exp, var_obs, pval = TRUE) { # # Enlarge the number of dimensions of var_exp and var_obs to 7 if necessary @@ -83,7 +152,9 @@ RatioSDRMS <- function(var_exp, var_obs, pval = TRUE) { # enlratiormssd } - +#'@rdname RatioSDRMS +#'@importFrom stats sd pf +#'@export .RatioSDRMS <- function(exp, obs, pval = TRUE) { # diff --git a/R/Regression.R b/R/Regression.R index 2f2aa4c5116acd17523346ef00e70f15757e74d0..2afd14b81905d53b285bff1f9374286bc320342e 100644 --- a/R/Regression.R +++ b/R/Regression.R @@ -1,3 +1,67 @@ +#'Computes The Regression Of An Array On Another Along A Dimension +#' +#'Computes the regression of the input matrice vary on the input matrice varx +#'along the posREG dimension by least square fitting. Provides the slope of +#'the regression, the associated confidence interval, and the intercept.\cr +#'Provides also the vary data filtered out from the regression onto varx.\cr +#'The confidence interval relies on a student-T distribution. +#' +#'@param vary Array of any number of dimensions up to 10. +#'@param varx Array of any number of dimensions up to 10. +#' Same dimensions as vary. +#'@param posREG Position along which to compute the regression. +#' +#'@return +#' \item{$regression}{ +#' Array with same dimensions as varx and vary except along posREG +#' dimension which is replaced by a length 4 dimension, corresponding +#' to the lower limit of the 95\% confidence interval, the slope, +#' the upper limit of the 95\% confidence interval and the intercept. +#' } +#' \item{$filtered}{ +#' Same dimensions as vary filtered out from the regression onto varx +#' along the posREG dimension. +#' } +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2013-05 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN +#'@examples +#'# See examples on Load() to understand the first lines in this example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' output = 'lonlat', latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'sampleData$mod <- Season(sampleData$mod, 4, 11, 12, 2) +#'sampleData$obs <- Season(sampleData$obs, 4, 11, 12, 2) +#'reg <- Regression(Mean1Dim(sampleData$mod, 2), +#' Mean1Dim(sampleData$obs, 2), 2) +#'PlotEquiMap(reg$regression[1, 2, 1, , ], sampleData$lon, sampleData$lat, +#' toptitle='Regression of the prediction on the observations', +#' sizetit = 0.5) +#' +#'@importFrom stats lm na.omit confint +#'@export Regression <- function(vary, varx, posREG = 2) { # # Enlarge the size of varx and vary to 10 diff --git a/R/SVD.R b/R/SVD.R index 86eb70926138feebab510a1511a17fa12f9c58ce..687715b32f84cb3178ae2ffc92d05b059c877b07 100644 --- a/R/SVD.R +++ b/R/SVD.R @@ -1,3 +1,105 @@ +#'Single Value Decomposition (Maximum Covariance Analysis) +#' +#'Computes a Maximum Covariance Analysis (MCA) between vary and varx, both +#'of dimensions c(n. of time steps, n. of latitudes, n. of longitudes), each +#'over a region of interest, e.g.: prlr over Europe and tos over North Atlantic. +#'The input fields are latitude-weighted by default (can be adjustable via +#'\code{weight}).\cr +#'Returns a vector of squared covariance fraction (SCFs) explained by +#'each pair of covariability modes, a vector of correlation coefficient +#'(RUVs) between expansion coefficients (ECs) that measures their linear +#'relationship, and a set of regression (MCAs) associated with the +#'covariability modes (ECs). Note that MCAs are 'homogeneous' patterns obtained +#'as regression/correlation between each field (predictor, predictand) +#'and its expansion coefficient.\cr +#'The MCA is computed by default with the covariance matrix. It can be computed +#'with the correlation matrix by setting \code{corr = TRUE}. +#' +#'@param vary Array containing the anomalies field for the predictor. The +#' expected dimensions are c(n. of time steps, n. of latitudes, n. of +#' longitudes). +#'@param varx Array containing the anomalies field for the predictand. The +#' expected dimensions are c(n. of time steps, n. of latitudes, n. of +#' longitudes). +#'@param laty Vector of latitudes of the array \code{vary}. Only required if +#' \code{weight = TRUE}. +#'@param latx Vector of latitudes of the array \code{varx}. Only required if +#' \code{weight = TRUE}. +#'@param nmodes Number of ECs/MCAs/modes retained and provided in the outputs. +#'@param corr Whether to compute the MCA over a covariance matrix (FALSE) or +#' a correlation matrix (TRUE). +#'@param weight Whether to apply latitude weights on the input fields or not. +#' TRUE by default. +#' +#'@return +#' \item{$SC}{ +#'Vector of squared covariance (n. of modes). +#' } +#' \item{$SCFs}{ +#' Vector of squared covariance fractions (n. of modes). +#' } +#' \item{$RUVs}{ +#' Vector of correlations between expansion coefficients (n. of modes). +#' } +#' \item{$ECs_U}{ +#' Array of expansion coefficients of predictor field (n. of time steps, +#' n. of modes). +#' } +#' \item{$MCAs_U}{ +#' Array of covariability patterns of predictor field (c(dim), n. of modes). +#' } +#' \item{$ECs_V}{ +#' Array of expansion coefficients of predictand field (n. of time steps, +#' n. of modes). +#' } +#' \item{$MCAs_V}{ +#' Array of covariability patterns of predictand field (c(dim), n. of modes). +#' } +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2010-09 (J.-G. Serrano, \email{javier.garcia@@bsc.es}) - Original code\cr +#'1.0 - 2016-04 (N. Manubens, \email{nicolau.manubens@@bsc.es}) - Formatting to R CRAN +#'@examples +#'# See examples on Load() to understand the first lines in this example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' leadtimemin = 1, leadtimemax = 4, output = 'lonlat', +#' latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' leadtimemin = 1, +#' leadtimemax = 4, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'# This example computes the ECs and MCAs along forecast horizons and plots the +#'# one that explains the greatest amount of variability. The example data is +#'# very low resolution so it does not make a lot of sense. +#'ano <- Ano_CrossValid(sampleData$mod, sampleData$obs) +#'mca <- SVD(Mean1Dim(ano$ano_exp, 2)[1, , 1, , ], +#' Mean1Dim(ano$ano_obs, 2)[1, , 1, , ], +#' sampleData$lat, sampleData$lat) +#'PlotEquiMap(mca$MCAs_U[1, , ], sampleData$lon, sampleData$lat) +#'plot(mca$ECs_U[1, ]) +#'PlotEquiMap(mca$MCAs_V[1, , ], sampleData$lon, sampleData$lat) +#'plot(mca$ECs_V[1, ]) +#' +#'@importFrom stats sd cor lm +#'@export SVD <- function(vary, varx, laty = NULL, latx = NULL, nmodes = 15, corr = FALSE, weight = TRUE) { # Checking vary diff --git a/R/Season.R b/R/Season.R index bf549a7e075b5647573a709c6c7f0875c931a8c2..d9f95a51cd33a77d4a2f29079a21ca3a5d2f49d3 100644 --- a/R/Season.R +++ b/R/Season.R @@ -1,3 +1,41 @@ +#'Computes Seasonal Means +#' +#'Computes seasonal means on timeseries organized in a array of any number of +#'dimensions up to 10 dimensions where the time dimension is one of those 10 +#'dimensions. +#' +#'@param var Array containing the timeseries along one of its dimensions. +#'@param posdim Dimension along which to compute seasonal means = Time +#' dimension. +#'@param monini an integer indicating the first month of the time series: 1 to +#' 12. +#'@param moninf an integer indicating the month when to start the seasonal +#' means: 1 to 12. +#'@param monsup an integer indicating the month when to stop the seasonal +#' means: 1 to 12. +#' +#'@return Array with the same dimensions as var except along the posdim +#' dimension whose length corresponds to the number of seasons. Partial +#' seasons are not accounted for. +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'leadtimes_dimension <- 4 +#'initial_month <- 11 +#'mean_start_month <- 12 +#'mean_stop_month <- 2 +#'season_means_mod <- Season(sampleData$mod, leadtimes_dimension, initial_month, +#' mean_start_month, mean_stop_month) +#'season_means_obs <- Season(sampleData$obs, leadtimes_dimension, initial_month, +#' mean_start_month, mean_stop_month) +#'PlotAno(season_means_mod, season_means_obs, startDates, +#' toptitle = paste('winter (DJF) temperatures'), ytitle = c('K'), +#' legends = 'ERSST', biglab = FALSE, fileout = 'tos_season_means.eps') +#'@export Season <- function(var, posdim = 4, monini, moninf, monsup) { while (monsup < moninf) { monsup <- monsup + 12 diff --git a/R/SelIndices.R b/R/SelIndices.R index 59f0a1afab57f0c8f5631f6dd733a6a3ff4887aa..6ef21ed8c132ebac7833965cc822434cdbee20fc 100644 --- a/R/SelIndices.R +++ b/R/SelIndices.R @@ -1,3 +1,29 @@ +#'Slices A Matrix Along A Dimension +#' +#'This function selects a subset of ensemble members from an array containing +#'any number of dimensions. +#' +#'@param var An array with any number of dimensions. +#'@param posdim The dimension along which the ensemble subset should be +#' selected. +#'@param limits The lower and upper limits for the selection of ensemble +#' members along the posdim dimension. +#' +#'@return The subsetted array. +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2011-04 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN +#'@examples +#'a <- array(rnorm(24), dim = c(2, 3, 4, 1)) +#'print(a) +#'print(a[, , 2:3, ]) +#'print(dim(a[, , 2:3, ])) +#'print(SelIndices(a, 3, c(2, 3))) +#'print(dim(SelIndices(a, 3, c(2, 3)))) +#' +#'@export SelIndices <- function(var, posdim, limits) { # # A few security checks diff --git a/R/Smoothing.R b/R/Smoothing.R index c93dfc827689059eda13a710a27ce328812a6f60..65aac018e861d6956ea012cfc40f341907ac18c4 100644 --- a/R/Smoothing.R +++ b/R/Smoothing.R @@ -1,3 +1,38 @@ +#'Smoothes An Array Along A Dimension +#' +#'Smoothes an array of any number of dimensions along one of its dimensions. +#' +#'@param var Array to be smoothed along one of its dimension (typically the +#' forecast time dimension). +#'@param runmeanlen Running mean length in number of sampling units +#' (typically months). +#'@param numdimt Dimension to smooth. +#' +#'@return Array with same the dimensions as 'var' but smoothed along the +#' 'numdimt'-th dimension. +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to R CRAN\cr +#'1.1 - 2015-05 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Adding +#' security checks, fixing computation in cases where runmeanlen is odd and +#' making it able to work on arrays of any number of dimensions. +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'ano_exp <- Ano(sampleData$mod, clim$clim_exp) +#'ano_obs <- Ano(sampleData$obs, clim$clim_obs) +#'runmean_months <- 12 +#'dim_to_smooth <- 4 # Smooth along lead-times +#'smooth_ano_exp <- Smoothing(ano_exp, runmean_months, dim_to_smooth) +#'smooth_ano_obs <- Smoothing(ano_obs, runmean_months, dim_to_smooth) +#'PlotAno(smooth_ano_exp, smooth_ano_obs, startDates, +#' toptitle = "Smoothed Mediterranean mean SST", ytitle = "K", +#' fileout = "tos_smoothed_ano.eps") +#'@import plyr +#'@export Smoothing <- function(var, runmeanlen = 12, numdimt = 4) { # Check var if (!is.numeric(var)) { diff --git a/R/Spectrum.R b/R/Spectrum.R index 6c5d379d8942c8ecc3f33a39e4122598d289732e..bb9b2ca6623f3e3b48dbd243c65c6ca268c108e4 100644 --- a/R/Spectrum.R +++ b/R/Spectrum.R @@ -1,3 +1,41 @@ +#'Estimates Frequency Spectrum +#' +#'This function estimates the frequency spectrum of the xdata array together +#'with its 95\% and 99\% significance level. The output is provided as an +#'array with dimensions c(number of frequencies, 4). The column contains the +#'frequency values, the power, the 95\% significance level and the 99\% one.\cr +#'The spectrum estimation relies on a R built-in function and the significance +#'levels are estimated by a Monte-Carlo method. +#' +#'@param xdata Array of which the frequency spectrum is required. +#' +#'@return Frequency spectrum with dimensions c(number of frequencies, 4). The +#' column contains the frequency values, the power, the 95\% significance +#' level and the 99\% one. +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2012-02 (V. Guemas, \email{virginie.guemas@@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to CRAN +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#' +#'ensmod <- Mean1Dim(sampleData$mod, 2) +#'for (jstartdate in 1:3) { +#' spectrum <- Spectrum(ensmod[1, jstartdate, ]) +#' for (jlen in 1:dim(spectrum)[1]) { +#' if (spectrum[jlen, 2] > spectrum[jlen, 4]) { +#' ensmod[1, jstartdate, ] <- Filter(ensmod[1, jstartdate, ], +#' spectrum[jlen, 1]) +#' } +#' } +#'} +#'PlotAno(InsertDim(ensmod, 2, 1), sdates = startDates, fileout = +#' 'filtered_ensemble_mean.eps') +#' +#'@importFrom stats spectrum cor rnorm sd quantile +#'@export Spectrum <- function(xdata) { print('Warning : Your data are assumed to be evenly spaced in time') xdata <- xdata[is.na(xdata) == FALSE] diff --git a/R/Spread.R b/R/Spread.R index 53f59aa05bb8574e27290576827f7ecc10ca57b9..5a8e01896237b882672b8ab69aa76db64b740565 100644 --- a/R/Spread.R +++ b/R/Spread.R @@ -1,3 +1,83 @@ +#'Computes InterQuartile Range, Maximum-Minimum, Standard Deviation and +#'Median Absolute Deviation of the Ensemble Members +#' +#'Computes the InterQuartile Range, the Maximum minus Mininum, the Standard +#'Deviation and the Median Absolute Deviation along the list of dimensions +#'provided by the posdim argument (typically along the ensemble member and +#'start date dimension).\cr +#'The confidence interval is optionally computed by bootstrapping. +#' +#'@param var Matrix of any number of dimensions up to 10. +#'@param posdim List of dimensions along which to compute IQR/MaxMin/SD/MAD. +#'@param narm TRUE/FALSE if NA removed/kept for computation. Default = TRUE. +#'@param siglev Confidence level of the computed confidence interval. +#' 0.95 by default. +#'@param conf Whether to compute the confidence intervals or not. +#' TRUE by default. +#' +#'@details +#'Example:\cr +#'--------\cr +#'To compute IQR, Max-Min, SD & MAD accross the members and start dates of +#'var output from \code{Load()} or \code{Ano()} or \code{Ano_CrossValid()}, +#'call:\cr +#' spread(var, posdim = c(2, 3), narm = TRUE) +#' +#'@return +#'Matrix with the same dimensions as var except along the first posdim +#'dimension which is replaced by a length 1 or 3 dimension, corresponding to +#'the lower limit of the \code{siglev}\% confidence interval +#'(only present if \code{conf = TRUE}), the spread, and the upper limit of +#'the \code{siglev}\% confidence interval (only present if \code{conf = TRUE}) +#'for each experiment/leadtime/latitude/longitude. +#' \item{$iqr}{ +#' InterQuartile Range. +#' } +#' \item{$maxmin}{ +#' Maximum - Minimum. +#' } +#' \item{$sd}{ +#' Standard Deviation. +#' } +#' \item{$mad}{ +#' Median Absolute Deviation. +#' } +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to CRAN +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'ano_exp <- Ano(sampleData$mod, clim$clim_exp) +#'runmean_months <- 12 +#'dim_to_smooth <- 4 # Smooth along lead-times +#'smooth_ano_exp <- Smoothing(ano_exp, runmean_months, dim_to_smooth) +#'smooth_ano_exp_m_sub <- smooth_ano_exp - InsertDim(Mean1Dim(smooth_ano_exp, 2, +#' narm = TRUE), 2, dim(smooth_ano_exp)[2]) +#'spread <- Spread(smooth_ano_exp_m_sub, c(2, 3)) +#'PlotVsLTime(spread$iqr, +#' toptitle = "Inter-Quartile Range between ensemble members", +#' ytitle = "K", monini = 11, limits = NULL, +#' listexp = c('CMIP5 IC3'), listobs = c('ERSST'), biglab = FALSE, +#' hlines = c(0), fileout = 'tos_iqr.eps') +#'PlotVsLTime(spread$maxmin, toptitle = "Maximum minus minimum of the members", +#' ytitle = "K", monini = 11, limits = NULL, +#' listexp = c('CMIP5 IC3'), listobs = c('ERSST'), biglab = FALSE, +#' hlines = c(0), fileout = 'tos_maxmin.eps') +#'PlotVsLTime(spread$sd, toptitle = "Standard deviation of the members", +#' ytitle = "K", monini = 11, limits = NULL, +#' listexp = c('CMIP5 IC3'), listobs = c('ERSST'), biglab = FALSE, +#' hlines = c(0), fileout = 'tos_sd.eps') +#'PlotVsLTime(spread$mad, toptitle = "Median Absolute Deviation of the members", +#' ytitle = "K", monini = 11, limits = NULL, +#' listexp = c('CMIP5 IC3'), listobs = c('ERSST'), biglab = FALSE, +#' hlines = c(0), fileout = 'tos_mad.eps') +#' +#'@importFrom stats IQR sd mad runif quantile +#'@export Spread <- function(var, posdim = 2, narm = TRUE, siglev = 0.95, conf = TRUE) { # # Enlarge the size of var to 10 and move all posdim to first position diff --git a/R/StatSeasAtlHurr.R b/R/StatSeasAtlHurr.R index 73ce6322ea96b4416960733d888d797f8b42f9e6..43d41b651c84e2ebe1429a598210b893c641a7b7 100644 --- a/R/StatSeasAtlHurr.R +++ b/R/StatSeasAtlHurr.R @@ -1,3 +1,73 @@ +#'Compute estimate of seasonal mean of Atlantic hurricane activity +#' +#'Compute one of G. Villarini's statistically downscaled measure of mean +#'Atlantic hurricane activity and its variance. The hurricane activity is +#'estimated using seasonal averages of sea surface temperature anomalies over +#'the tropical Atlantic (bounded by 10N-25N and 80W-20W) and the tropics at +#'large (bounded by 30N-30S). The anomalies are for the JJASON season.\cr +#'The estimated seasonal average is either 1) number of hurricanes, 2) number +#'of tropical cyclones with lifetime >=48h or 3) power dissipation index +#'(PDI; in 10^11 m^3 s^{-2}).\cr +#'The statistical models used in this function are described in\cr +#' +#'@param atlano Array of Atlantic sea surface temperature anomalies. +#' Must have the same dimension as tropano. +#'@param tropano Array of tropical sea surface temperature anomalies. +#' Must have the same dimension as atlano. +#'@param hrvar The seasonal average to be estimated. The options are either\cr +#' "HR" (hurricanes) \cr +#' "TC" (tropical cyclones with lifetime >=48h) \cr +#' "PDI" (power dissipation index) \cr +#' +#'@return A list composed of two matrices:\cr +#'\enumerate{ +#' \item{ +#' A matrix (mean) with the seasonal average values of the desired quantity.\cr +#' } +#' \item{ +#' A matrix (var) of the variance of that quantity.\cr +#' } +#'} +#'The dimensions of the two matrices are the same as the dimensions of +#' atlano/tropano. +#' +#'@keywords datagen +#'@references +#'Villarini et al. (2010) Mon Wea Rev, 138, 2681-2705.\cr +#'Villarini et al. (2012) Mon Wea Rev, 140, 44-65.\cr +#'Villarini et al. (2012) J Clim, 25, 625-637.\cr +#'An example of how the function can be used in hurricane forecast studies +#' is given in\cr +#'Caron, L.-P. et al. (2014) Multi-year prediction skill of Atlantic hurricane +#' activity in CMIP5 decadal hindcasts. Climate Dynamics, 42, 2675-2690. +#' doi:10.1007/s00382-013-1773-1. +#'@author History:\cr +#'0.1 - 2015-11 (Louis-Philippe Caron, \email{louis-philippe.caron@@bsc.es}) - Original code +#'@examples +#'# Let AtlAno represents 5 different 5-year forecasts of seasonally averaged +#'# Atlantic sea surface temperature anomalies. +#'AtlAno <- matrix(c(-0.31, -0.36, 0.26, -0.16, -0.16, +#' -0.06, -0.22, -0.31, -0.36, -0.39, +#' 0.20, -0.14, 0.12, 0.22, 0.02, +#' -0.28, 0.26, -0.10, 0.18, 0.33, +#' 0.45, 0.46, 0.04, 0.12, 0.21), +#' nrow = 5, ncol = 5) +#'# Let TropAno represents 5 corresponding 5-year forecasts of seasonally averaged +#'# tropical sea surface temperature anomalies. +#'TropAno <- matrix(c(-0.22, -.13, 0.07, -0.16, -0.15, +#' 0.00, -0.03, -0.22, -0.13, -0.10, +#' 0.07, -0.07, 0.17, 0.10, -0.15, +#' -0.01, 0.08, 0.07, 0.17, 0.13, +#' 0.16, 0.15, -0.09, 0.03, 0.27), +#' nrow = 5, ncol = 5) +#'# The seasonal average of hurricanes for each of the five forecasted years, +#'# for each forecast, would then be given by +#'hr_count <- StatSeasAtlHurr(atlano = AtlAno, +#' tropano = TropAno, +#' hrvar = 'HR') +#'print(hr_count$mean) +#' +#'@export StatSeasAtlHurr <- function(atlano = NULL, tropano = NULL, hrvar = "HR") { # Verify that variables are either TC, HR or PDI. # ----------------------------------------------- diff --git a/R/Subset.R b/R/Subset.R index c82b0c67f6804ab2a3ce9127ede530a6fbe4cbb2..7c1e9dcb560c49ba77d3347fad8482138ff7aeb1 100644 --- a/R/Subset.R +++ b/R/Subset.R @@ -1,3 +1,39 @@ +#'Subset a Data Array +#' +#'This function allows to subset (i.e. slice, take a chunk of) an array, in a +#'similar way as done in the function \code{take()} in the package plyr. There +#'are two main inprovements:\cr\cr +#'The input array can have dimension names, either +#'in \code{names(dim(x))} or in the attribute 'dimensions', and the dimensions +#'to subset along can be specified via the parameter \code{along} either with +#'integer indices or either by their name.\cr\cr +#'There are additional ways to adjust which dimensions are dropped in the +#'resulting array: either to drop all, to drop none, to drop only the ones that +#'have been sliced or to drop only the ones that have not been sliced.\cr\cr +#'If an array is provided without dimension names, dimension names taken from +#'the parameter \code{dim_names} will be added to the array. +#' +#'@param x A multidimensional array to be sliced. It can have dimension names +#' either in \code{names(dim(x))} or either in the attribute 'dimensions'. +#'@param along Vector with references to the dimensions to take the subset +#' from: either integers or dimension names. +#'@param indices List of indices to take from each dimension specified in +#' 'along'. If a single dimension is specified in 'along' the indices can be +#' directly provided as a single integer or as a vector. +#'@param drop Whether to drop all the dimensions of length 1 in the resulting +#' array, none, only those that are specified in 'along', or only those that +#' are not specified in 'along'. The possible values are, respectively: 'all' +#' or TRUE, 'none' or FALSE, 'selected', and 'non-selected'. +#' +#'@keywords dplot +#'@examples +#'subset <- Subset(sampleMap$mod, c('dataset', 'sdate', 'ftime'), +#' list(1, 1, 1), drop = 'selected') +#'PlotLayout(PlotEquiMap, c('lat', 'lon'), subset, +#' sampleMap$lon, sampleMap$lat, +#' titles = paste('Member', 1:3)) +#' +#'@export Subset <- function(x, along, indices, drop = FALSE) { # Check x if (!is.array(x)) { diff --git a/R/ToyModel.R b/R/ToyModel.R index c5325acea4be5966a94c97ddbaa3937136ac7a4f..f0c9a22dfeee70e38ba98424cb45e3ff5294bb70 100644 --- a/R/ToyModel.R +++ b/R/ToyModel.R @@ -1,3 +1,108 @@ +#'Synthetic forecast generator imitating seasonal to decadal forecasts. The +#'components of a forecast: (1) predictabiltiy (2) forecast error (3) +#'non-stationarity and (4) ensemble generation. The forecast can be computed +#'for real observations or observations generated artifically. +#' +#'The toymodel is based on the model presented in Weigel et al. (2008) QJRS +#'with an extension to consider non-stationary distributions prescribing a +#'linear trend. The toymodel allows to generate an aritifical forecast +#'based on obsevations provided by the input (from Load) or artificially +#'generated observations based on the input parameters (sig, trend). +#'The forecast can be specfied for any number of start-dates, lead-time and +#'ensemble members. It imitates components of a forecast: (1) predictabiltiy +#'(2) forecast error (3) non-stationarity and (4) ensemble generation. +#'The forecast can be computed for real observations or observations generated +#'artifically. +#' +#'@param alpha Predicabiltiy of the forecast on the observed residuals +#' Must be a scalar 0 < alpha < 1. +#'@param beta Standard deviation of forecast error +#' Must be a scalar 0 < beta < 1. +#'@param gamma Factor on the linear trend to sample model uncertainty. Can be +#' a scalar or a vector of scalars -inf < gammay < inf. +#' Defining a scalar results in multiple forecast, corresponding to different +#' models with different trends. +#'@param sig Standard deviation of the residual variability of the forecast. +#' If observations are provided 'sig' is computed from the observations. +#'@param trend Linear trend of the forecast. The same trend is used for each +#' lead-time. If observations are provided the 'trend' is computed from the +#' observations, with potentially different trends for each lead-time. The +#' trend has no unit and needs to be defined according to the time vector +#' [1,2,3,... nstartd]. +#'@param nstartd Number of start-dates of the forecast. +#' If observations are provided the 'nstartd' is computed from the observations. +#'@param nleadt Number of lead-times of the forecats. +#' If observations are provided the 'nleadt' is computed from the observations. +#'@param nmemb Number of members of the forecasts. +#'@param obsini Observations that can be used in the synthetic forecast coming +#' from Load (anomalies are expected). If no observations are provided +#' artifical observations are generated based on Gaussian variaiblity with +#' standard deviation from 'sig' and linear trend from 'trend'. +#'@param fxerr Provides a fixed error of the forecast instead of generating +#' one from the level of beta. This allows to perform pair of forecasts with +#' the same conditional error as required for instance in an attribution context. +#' +#'@return List of forecast with $mod including the forecast and $obs the +#' observations. The dimensions correspond to +#' c(length(gamma), nmemb, nstartd, nleadt) +#' +#'@keywords datagen +#'@author History:\cr +#'1.0 - 2014-08 (O.Bellprat) - Original code +#'1.1 - 2016-02 (O.Bellprat) - Include security check for parameters +#'@examples +#'# Example 1: Generate forecast with artifical observations +#'# Seasonal prediction example +#'a <- 0.1 +#'b <- 0.3 +#'g <- 1 +#'sig <- 1 +#'t <- 0.02 +#'ntd <- 30 +#'nlt <- 4 +#'nm <- 10 +#'toyforecast <- ToyModel(alpha = a, beta = b, gamma = g, sig = sig, trend = t, +#' nstartd = ntd, nleadt = nlt, nmemb = nm) +#' +#'# Example 2: Generate forecast from loaded observations +#'# Decadal prediction example +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' output = 'areave', latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' output = 'areave', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#' +#'a <- 0.1 +#'b <- 0.3 +#'g <- 1 +#'nm <- 10 +#' +#'toyforecast <- ToyModel(alpha = a, beta = b, gamma = g, nmemb = nm, +#' obsini = sampleData$obs, nstartd = 5, nleadt = 60) +#'PlotAno(toyforecast$mod, toyforecast$obs, startDates, +#' toptitle = c("Synthetic decadal temperature prediction"), +#' fileout = "ex_toymodel.eps") +#' +#'@importFrom stats rnorm +#'@export ToyModel <- function(alpha = 0.1, beta = 0.4, gamma = 1, sig = 1, trend = 0, nstartd = 30, nleadt = 4, nmemb = 10, obsini = NULL, fxerr = NULL) { diff --git a/R/Trend.R b/R/Trend.R index e035df2ab27a6dd71302661db6c8875bd10f92d4..15ec7ebe91338be57dbc456994e6942ffbfc8ac0 100644 --- a/R/Trend.R +++ b/R/Trend.R @@ -1,3 +1,58 @@ +#'Computes the Trend of the Ensemble Mean +#' +#'Computes the trend along the forecast time of the ensemble mean by least +#'square fitting, and the associated error interval.\cr +#'Trend() also provides the time series of the detrended ensemble mean +#'forecasts.\cr +#'The confidence interval relies on a student-T distribution.\cr\cr +#'.Trend provides the same functionality but taking a matrix ensemble members +#'as input (exp). +#' +#'@param var Array of any number of dimensions up to 10. +#'@param exp M by N matrix of M forecasts from N ensemble members. +#'@param interval Number of months/years between 2 points along posTR +#' dimension.\cr +#' Default = 1.\cr +#' The trend would be provided in number of units per month or year. +#'@param siglev Confidence level for the computation of confidence interval. +#' 0.95 by default. +#'@param conf Whether to compute the confidence levels or not. TRUE by default. +#'@param posTR Position along which to compute the trend. +#' +#'@return +#'\item{$trend}{ +#' The intercept and slope coefficients for the least squares fitting of the +#' trend. +#'} +#'\item{$conf.int}{ +#' Corresponding to the limits of the \code{siglev}\% confidence interval +#' (only present if \code{conf = TRUE}) for the slope coefficient. +#'} +#'\item{$detrended}{ +#' Same dimensions as var with linearly detrended var along the posTR +#' dimension. +#'} +#' +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2011-05 (V. Guemas, \email{virginie.guemas@@ic3.cat}) - Original code\cr +#'1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@@ic3.cat}) - Formatting to CRAN\cr +#'2.0 - 2017-02 (A. Hunter, \email{alasdair.hunter@@bsc.es}) - Adapt to veriApply() +#'@examples +#'# Load sample data as in Load() example: +#'example(Load) +#'months_between_startdates <- 60 +#'trend <- Trend(sampleData$obs, 3, months_between_startdates) +#'PlotVsLTime(trend$trend, toptitle = "trend", ytitle = "K / (5 year)", +#' monini = 11, limits = c(-1,1), listexp = c('CMIP5 IC3'), +#' listobs = c('ERSST'), biglab = FALSE, hlines = 0, +#' fileout = 'tos_obs_trend.eps') +#'PlotAno(trend$detrended, NULL, startDates, +#' toptitle = 'detrended anomalies (along the startdates)', ytitle = 'K', +#' legends = 'ERSST', biglab = FALSE, fileout = 'tos_detrended_obs.eps') +#' +#'@rdname Trend +#'@export Trend <- function(var, posTR = 2, interval = 1, siglev = 0.95, conf = TRUE) { # # Enlarge the size of var to 10 and move posTR to first position @@ -79,6 +134,9 @@ Trend <- function(var, posTR = 2, interval = 1, siglev = 0.95, conf = TRUE) { invisible(list(trend = enltrend, detrended = enldetrend)) } +#'@rdname Trend +#'@importFrom stats lm na.omit confint +#'@export .Trend <- function(exp, interval = 1, siglev = 0.95, conf = TRUE) { ensmean <- rowMeans(exp, na.rm = TRUE) diff --git a/R/UltimateBrier.R b/R/UltimateBrier.R index 23743b7719365b74d5722908b687671f5912fffe..01f407c8c979d0a9a2f74e9910a9314aca339791 100644 --- a/R/UltimateBrier.R +++ b/R/UltimateBrier.R @@ -1,3 +1,108 @@ +#'Computes Brier Scores +#' +#'Interface to compute probabilistic scores (Brier Score, Brier Skill Score) +#'from data obtained from s2dverification. +#' +#'@param ano_exp Array of forecast anomalies, as provided by \code{Ano()}. +#' Dimensions c(n. of experimental datasets, n. of members, n. of start dates, +#' n. of forecast time steps, n. of latitudes, n. of longitudes). Dimensions +#' in other orders are also supported. See parameters \code{posdatasets}, +#' \code{posmemb} and \code{posdates}. +#'@param ano_obs Array of observational reference anomalies, as provided by +#' \code{Ano()}. Dimensions c(n. of observational reference datasets, +#' n. of members, n. of start dates, n. of forecast time steps, +#' n. of latitudes, n. of longitudes). Dimensions in other orders are also +#' supported. See parameters \code{posdatasets}, \code{posmemb} and +#' \code{posdates}. +#'@param posdatasets Expected position of dimension corresponding to the +#' different evaluated datasets in input data (ano_exp and ano_obs). +#' By default 1. +#'@param posmemb Expected position of dimension corresponding to members in +#' input data (ano_exp and ano_obs). By default 2. +#'@param posdates Expected position of dimension corresponding to starting +#' dates in input data (ano_exp and ano_obs). By default 3. +#'@param quantile Flag to stipulate whether a quantile (TRUE) or a threshold +#' (FALSE) is used to estimate the forecast and observed probabilities. +#' Takes TRUE by default. +#'@param thr Values to be used as quantiles if 'quantile' is TRUE or as +#' thresholds if 'quantile' is FALSE. Takes by default \code{c(0.05, 0.95)} +#' if 'quantile' is TRUE. +#'@param type Type of score desired. Can take the following values: +#'\itemize{ +#' \item{'BS': Simple Brier Score.} +#' \item{'FairEnsembleBS': Corrected Brier Score computed across ensemble +#' members.} +#' \item{'FairStartDatesBS': Corrected Brier Score computed across starting +#' dates.} +#' \item{'BSS': Simple Brier Skill Score.} +#' \item{'FairEnsembleBSS': Corrected Brier Skill Score computed across +#' ensemble members.} +#' \item{'FairStartDatesBSS': Corrected Brier Skill Score computed across +#' starting dates.} +#'} +#'@param decomposition Flag to determine whether the decomposition of the +#' Brier Score into its components should be provided (TRUE) or not (FALSE). +#' Takes TRUE by default. The decomposition will be computed only if 'type' +#' is 'BS' or 'FairStartDatesBS'. +#'@return +#'If 'type' is 'FairEnsembleBS', 'BSS', 'FairEnsemblesBSS' or +#''FairStartDatesBSS' or 'decomposition' is FALSE and 'type' is 'BS' or +#''FairStartDatesBS', the Brier Score or Brier Skill Score will be returned +#'respectively. +#'If 'decomposition' is TRUE and 'type' is 'BS' or 'FairStartDatesBS' the +#'returned value is a named list with the following entries: +#' \itemize{ +#' \item{'BS': Brier Score.} +#' \item{'REL': Reliability component.} +#' \item{'UNC': Uncertainty component.} +#' \item{'RES': Resolution component.} +#' } +#'The dimensions of each of these arrays will be c(n. of experimental datasets, +#'n. of observational reference datasets, n. of bins, the rest of input +#'dimensions except for the ones pointed by 'posmemb' and 'posdates'). +#'@keywords datagen +#'@author History:\cr +#'0.1 - 2015-05 (V. Guemas \email{virginie.guemas@@bsc.es},\cr +#' C. Prodhomme \email{chloe.prodhomme@@bsc.es},\cr +#' O. Bellprat \email{omar.bellprat@@bsc.es}\cr +#' V. Torralba \email{veronica.torralba@@bsc.es}\cr +#' N. Manubens, \email{nicolau.manubens@@bsc.es}) - First version +#'@examples +#'# See ?Load for an explanation on the first part of this example. +#' \dontrun{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'expA <- list(name = 'experiment', path = file.path(data_path, +#' 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', +#' '$VAR_NAME$_$START_DATE$.nc')) +#'obsX <- list(name = 'observation', path = file.path(data_path, +#' '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', +#' '$VAR_NAME$_$YEAR$$MONTH$.nc')) +#' +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(expA), list(obsX), startDates, +#' leadtimemin = 1, leadtimemax = 4, output = 'lonlat', +#' latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) +#' } +#' \dontshow{ +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), +#' c('observation'), startDates, +#' leadtimemin = 1, +#' leadtimemax = 4, +#' output = 'lonlat', +#' latmin = 27, latmax = 48, +#' lonmin = -12, lonmax = 40) +#' } +#'sampleData$mod <- Season(sampleData$mod, 4, 11, 12, 2) +#'sampleData$obs <- Season(sampleData$obs, 4, 11, 12, 2) +#'clim <- Clim(sampleData$mod, sampleData$obs) +#'ano_exp <- Ano(sampleData$mod, clim$clim_exp) +#'ano_obs <- Ano(sampleData$obs, clim$clim_obs) +#'bs <- UltimateBrier(ano_exp, ano_obs) +#'bss <- UltimateBrier(ano_exp, ano_obs, type = 'BSS') +#'@import SpecsVerification plyr +#'@export UltimateBrier <- function(ano_exp, ano_obs, posdatasets = 1, posmemb = 2, posdates = 3, quantile = TRUE, thr = c(5/100, 95/100), type = 'BS', diff --git a/R/clim.palette.R b/R/clim.palette.R index 5673c61d1e1d3bb53a069c36d8acab982aada337..d18dab165919da9b84e85ca06225ec68487c0c05 100644 --- a/R/clim.palette.R +++ b/R/clim.palette.R @@ -1,7 +1,28 @@ -clim.colors <- function(n, palette = "bluered") { - clim.palette(palette)(n) -} - +#'Generate Climate Color Palettes +#' +#'Generates a colorblind friendly color palette with color ranges useful in +#'climate temperature variable plotting. +#' +#'@param palette Which type of palette to generate: from blue through white +#' to red ('bluered'), from red through white to blue ('redblue'), from +#' yellow through orange to red ('yellowred'), or from red through orange +#' to red ('redyellow'). +#'@param n Number of colors to generate. +#' +#'@keywords datagen +#'@author History:\cr +#'0.0 - 2016-01 (N. Manubens, \email{nicolau.manubens@@bsc.es}) - Original code. +#'@examples +#'lims <- seq(-1, 1, length.out = 21) +#' +#'ColorBar(lims, color_fun = clim.palette('redyellow')) +#' +#'cols <- clim.colors(20) +#'ColorBar(lims, cols) +#' +#'@rdname clim.palette +#'@importFrom grDevices colorRampPalette +#'@export clim.palette <- function(palette = "bluered") { if (palette == "bluered") { colorbar <- colorRampPalette(rev(c("#67001f", "#b2182b", "#d6604d", @@ -30,3 +51,8 @@ clim.palette <- function(palette = "bluered") { } colorbar } +#'@rdname clim.palette +#'@export +clim.colors <- function(n, palette = "bluered") { + clim.palette(palette)(n) +} diff --git a/R/s2dverification.R b/R/s2dverification.R new file mode 100644 index 0000000000000000000000000000000000000000..d332f38dea348be4a5071dc174f46d5a6fc43c53 --- /dev/null +++ b/R/s2dverification.R @@ -0,0 +1,27 @@ +#'Set of Common Tools for Forecast Verification +#' +#'Set of tools to verify forecasts through the computation of typical +#'prediction scores against one or more observational datasets or reanalyses +#'(a reanalysis being a physical extrapolation of observations that relies on +#'the equations from a model, not a pure observational dataset). Intended for +#'seasonal to decadal climate forecasts although can be useful to verify other +#'kinds of forecasts. The package can be helpful in climate sciences for other +#'purposes than forecasting. +#' +#' \tabular{ll}{ +#'Package: \tab s2dverification\cr +#'Type: \tab Package\cr +#'Version: \tab 2.8.4\cr +#'Date: \tab 2019-01-30\cr +#'License: \tab LGPLv3\cr +#' } +#'Check an overview of the package functionalities and its modules at +#'\url{https://earth.bsc.es/gitlab/es/s2dverification/wikis/home}. +#'For more information load the package and check the help for each function +#'or the documentation attached to the package. +#' +#'@name s2dverification +#'@docType package +#'@author Nicolau Manubens \email{nicolau.manubens@bsc.es} +#'@keywords package datagen dynamic +"_PACKAGE" diff --git a/R/sampleDepthData.R b/R/sampleDepthData.R new file mode 100644 index 0000000000000000000000000000000000000000..6a0e09ceb69469745cc4ba6023577aade960f14a --- /dev/null +++ b/R/sampleDepthData.R @@ -0,0 +1,28 @@ +#'Sample of Experimental Data for Forecast Verification In Function Of +#'Latitudes And Depths +#' +#'This data set provides data in function of latitudes and depths for the +#'variable 'tos', i.e. sea surface temperature, from the decadal climate +#'prediction experiment run at IC3 in the context of the CMIP5 project.\cr +#'Its name within IC3 local database is 'i00k'. +#' +#'@usage data(sampleDepthData) +#'@format The data set provides with a variable named 'sampleDepthData'.\cr\cr +#' +#'sampleDepthData$exp is an array that contains the experimental data and the +#'dimension meanings and values are:\cr +#' c(# of experimental datasets, # of members, # of starting dates, +#' # of lead-times, # of depths, # of latitudes)\cr +#' c(1, 5, 3, 60, 7, 21)\cr\cr +#' +#'sampleDepthData$obs should be an array that contained the observational data +#'but in this sample is not defined (NULL).\cr\cr +#' +#'sampleDepthData$depths is an array with the 7 longitudes covered by the data.\cr\cr +#' +#'sampleDepthData$lat is an array with the 21 latitudes covered by the data.\cr\cr +#'@name sampleDepthData +#'@docType data +#'@author Nicolau Manubens \email{nicolau.manubens@bsc.es} +#'@keywords data +sampleDepthData <- function(){} diff --git a/R/sampleMap.R b/R/sampleMap.R new file mode 100644 index 0000000000000000000000000000000000000000..b10aff23f3791d301ea362f49315d74923ad7b57 --- /dev/null +++ b/R/sampleMap.R @@ -0,0 +1,46 @@ +#'Sample Of Observational And Experimental Data For Forecast Verification In Function Of Longitudes And Latitudes +#' +#'This data set provides data in function of longitudes and latitudes for the variable 'tos', i.e. sea surface temperature, over the mediterranean zone from the sample experimental and observational datasets attached to the package. See examples on how to use Load() for details.\cr\cr +#'The data is provided through a variable named 'sampleMap' and is structured as expected from the 'Load()' function in the 's2dverification' package if was called as follows:\cr\cr +#' \preformatted{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'exp <- list( +#' name = 'experiment', +#' path = file.path(data_path, 'model/$EXP_NAME$/monthly_mean', +#' '$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATES$.nc') +#' ) +#'obs <- list( +#' name = 'observation', +#' path = file.path(data_path, 'observation/$OBS_NAME$/monthly_mean', +#' '$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') +#' ) +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(exp), list(obs), startDates, +#' leadtimemin = 1, leadtimemax = 4, output = 'lonlat', +#' latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) +#' } +#'Check the documentation on 'Load()' in the package 's2dverification' for more information. +#' +#'@usage data(sampleMap) +#'@format +#'The data set provides with a variable named 'sampleMap'.\cr\cr +#' +#'sampleMap$mod is an array that contains the experimental data and the dimension meanings and values are:\cr +#' c(# of experimental datasets, # of members, # of starting dates, # of lead-times, # of latitudes, # of longitudes)\cr +#' c(1, 3, 5, 60, 2, 3)\cr\cr +#' +#'sampleMap$obs is an array that contains the observational data and the dimension meanings and values are:\cr +#' c(# of observational datasets, # of members, # of starting dates, # of lead-times, # of latitudes, # of longitudes)\cr +#' c(1, 1, 5, 60, 2, 3)\cr\cr +#' +#' sampleMap$lat is an array with the 2 latitudes covered by the data (see examples on Load() for details on why such low resolution).\cr\cr +#' +#' sampleMap$lon is an array with the 3 longitudes covered by the data (see examples on Load() for details on why such low resolution). +#' +#' @name sampleMap +#' @docType data +#' @author Nicolau Manubens \email{nicolau.manubens@bsc.es} +#' @keywords datasets +sampleMap <- function(){} + diff --git a/R/sampleTimeSeries.R b/R/sampleTimeSeries.R new file mode 100644 index 0000000000000000000000000000000000000000..86e38f426def6d1c7e40c7f847c34558693e79a1 --- /dev/null +++ b/R/sampleTimeSeries.R @@ -0,0 +1,48 @@ +#'Sample Of Observational And Experimental Data For Forecast Verification As Area Averages +#' +#'This data set provides area averaged data for the variable 'tos', i.e. sea +#'surface temperature, over the mediterranean zone from the example datasets +#'attached to the package. See examples on Load() for more details.\cr\cr +#'The data is provided through a variable named 'sampleTimeSeries' and is +#'structured as expected from the 'Load()' function in the 's2dverification' +#'package if was called as follows:\cr\cr +#' \preformatted{ +#'data_path <- system.file('sample_data', package = 's2dverification') +#'exp <- list( +#' name = 'experiment', +#' path = file.path(data_path, 'model/$EXP_NAME$/monthly_mean', +#' '$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATES$.nc') +#' ) +#'obs <- list( +#' name = 'observation', +#' path = file.path(data_path, 'observation/$OBS_NAME$/monthly_mean', +#' '$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') +#' ) +#'# Now we are ready to use Load(). +#'startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') +#'sampleData <- Load('tos', list(exp), list(obs), startDates, +#' output = 'areave', latmin = 27, latmax = 48, lonmin = -12, +#' lonmax = 40) +#' } +#'Check the documentation on 'Load()' in the package 's2dverification' for more information. +#' +#'@usage data(sampleTimeSeries) +#'@format The data set provides with a variable named 'sampleTimeSeries'.\cr\cr +#' +#'sampleTimeSeries$mod is an array that contains the experimental data and the dimension meanings and values are:\cr +#' c(# of experimental datasets, # of members, # of starting dates, # of lead-times)\cr +#' c(1, 3, 5, 60)\cr\cr +#' +#'sampleTimeSeries$obs is an array that contains the observational data and the dimension meanings and values are:\cr +#' c(# of observational datasets, # of members, # of starting dates, # of lead-times)\cr +#' c(1, 1, 5, 60)\cr\cr +#' +#'sampleTimeSeries$lat is an array with the 2 latitudes covered by the data that was area averaged to calculate the time series (see examples on Load() for details on why such low resolution).\cr\cr +#' +#'sampleTimeSeries$lon is an array with the 3 longitudes covered by the data that was area averaged to calculate the time series (see examples on Load() for details on why such low resolution). +#' +#' @name sampleTimeSeries +#' @docType data +#' @author Nicolau Manubens \email{nicolau.manubens@bsc.es} +#' @keywords datasets +sampleTimeSeries <- function(){} diff --git a/man/ACC.Rd b/man/ACC.Rd index d4d66aec9b832e2a387e415e5fccd96cf65e1863..17e2d7cf0369e6a2f3a6b1f6a4bf98e0f566e415 100644 --- a/man/ACC.Rd +++ b/man/ACC.Rd @@ -1,89 +1,92 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ACC.R \name{ACC} \alias{ACC} -\title{ -Computes Anomaly Correlation Coefficient -} -\description{ -Calculates the Anomaly Correlation Coefficient for the ensemble mean of each model and the corresponding references for each startdate and each leadtime.\cr -The domain of interest can be specified by providing the list of longitudes/latitudes (lon/lat) of the grid together with the corners of the domain:\cr -lonlatbox = c(lonmin, lonmax, latmin, latmax) -} +\title{Computes Anomaly Correlation Coefficient} \usage{ -ACC(var_exp, var_obs, lon = NULL, lat = NULL, lonlatbox = NULL, - conf = TRUE, conftype = "parametric", siglev = 0.95) +ACC(var_exp, var_obs, lon = NULL, lat = NULL, lonlatbox = NULL, + conf = TRUE, conftype = "parametric", siglev = 0.95) } \arguments{ - \item{var_exp}{ -Array of experimental anomalies with dimensions:\cr - c(nexp, nsdates, nltimes, nlat, nlon)\cr -or\cr - c(nexp, nsdates, nmembers, nltimes, nlat, nlon)\cr - } - \item{var_obs}{ -Array of observational anomalies, same dimensions as var_exp except along the first dimension and the second if it corresponds to the member dimension. - } - \item{lon}{ -Array of longitudes of the var_exp/var_obs grids, optional. - } - \item{lat}{ -Array of latitudes of the var_exp/var_obs grids, optional. - } - \item{lonlatbox}{ -Domain to select : c(lonmin, lonmax, latmin, latmax), optional. - } - \item{conf}{ -TRUE/FALSE: confidence intervals and significance level provided or not. - } - \item{conftype}{ -"parametric" provides a confidence interval for the ACC computed by a Fisher transformation and a significance level for the ACC from a one-sided student-T distribution.\cr -"bootstrap" provides a confidence interval for the ACC and MACC computed from bootstrapping on the members with 100 drawings with replacement.\cr -To guarantee the statistical robustness of the result, make sure that your experiments/oservations/startdates/leadtimes always have the same number of members. - } - \item{siglev}{ -The confidence level for the computed confidence intervals. - } +\item{var_exp}{Array of experimental anomalies with dimensions: +c(nexp, nsdates, nltimes, nlat, nlon) or +c(nexp, nsdates, nmembers, nltimes, nlat, nlon).} + +\item{var_obs}{Array of observational anomalies, same dimensions as var_exp +except along the first dimension and the second if it corresponds to the +member dimension.} + +\item{lon}{Array of longitudes of the var_exp/var_obs grids, optional.} + +\item{lat}{Array of latitudes of the var_exp/var_obs grids, optional.} + +\item{lonlatbox}{Domain to select: c(lonmin, lonmax, latmin, latmax), +optional.} + +\item{conf}{TRUE/FALSE: confidence intervals and significance level +provided or not.} + +\item{conftype}{"Parametric" provides a confidence interval for the ACC +computed by a Fisher transformation and a significance level for the ACC +from a one-sided student-T distribution. "Bootstrap" provides a confidence +interval for the ACC and MACC computed from bootstrapping on the members +with 100 drawings with replacement. To guarantee the statistical robustness +of the result, make sure that your experiments/oservations/startdates/ +leadtimes always have the same number of members.} + +\item{siglev}{The confidence level for the computed confidence intervals.} } \value{ - \item{ACC}{ -If \code{conf = TRUE}, array with dimensions:\cr - c(nexp, nobs, nsdates, nleadtimes, 4) \cr -The fifth dimension of length 4 corresponds to the lower limit of the \code{siglev}\% confidence interval, the ACC, the upper limit of the \code{siglev}\% confidence interval and the \code{siglev}\% significance level.\cr -If \code{conf = FALSE}, the array of the Anomaly Correlation Coefficient has dimensions:\cr - c(nexp, nobs, nsdates, nleadtimes). - } - \item{MACC}{ -The array of the Mean Anomaly Correlation Coefficient with dimensions:\cr - c(nexp, nobs, nleadtimes) - } +\item{ACC}{ + If \code{conf = TRUE}, array with dimensions: + c(nexp, nobs, nsdates, nleadtimes, 4) + The fifth dimension of length 4 corresponds to the lower limit of the + \code{siglev}\% confidence interval, the ACC, the upper limit of the + \code{siglev}\% confidence interval and the \code{siglev}\% significance + level. If \code{conf = FALSE}, the array of the Anomaly Correlation + Coefficient has dimensions c(nexp, nobs, nsdates, nleadtimes). +} +\item{MACC}{ + The array of the Mean Anomaly Correlation Coefficient with dimensions + c(nexp, nobs, nleadtimes). +} +} +\description{ +Calculates the Anomaly Correlation Coefficient for the ensemble mean of +each model and the corresponding references for each startdate and each +leadtime.\cr +The domain of interest can be specified by providing the list +of longitudes/latitudes (lon/lat) of the grid together with the corners +of the domain:\cr +lonlatbox = c(lonmin, lonmax, latmin, latmax). } - \examples{ # See ?Load for explanations on the first part of this example. - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') expA <- list(name = 'experiment', path = file.path(data_path, - 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', - '$VAR_NAME$_$START_DATE$.nc')) + 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', + '$VAR_NAME$_$START_DATE$.nc')) obsX <- list(name = 'observation', path = file.path(data_path, - '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', - '$VAR_NAME$_$YEAR$$MONTH$.nc')) + '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', + '$VAR_NAME$_$YEAR$$MONTH$.nc')) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(expA), list(obsX), startDates, - leadtimemin = 1, leadtimemax = 4, output = 'lonlat', - latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) - } - \dontshow{ + leadtimemin = 1, leadtimemax = 4, output = 'lonlat', + latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) + } + \dontshow{ startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - leadtimemin = 1, - leadtimemax = 4, - output = 'lonlat', - latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } + c('observation'), startDates, + leadtimemin = 1, + leadtimemax = 4, + output = 'lonlat', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } sampleData$mod <- Season(sampleData$mod, 4, 11, 12, 2) sampleData$obs <- Season(sampleData$obs, 4, 11, 12, 2) clim <- Clim(sampleData$mod, sampleData$obs) @@ -92,17 +95,19 @@ ano_obs <- Ano(sampleData$obs, clim$clim_obs) acc <- ACC(Mean1Dim(ano_exp, 2), Mean1Dim(ano_obs, 2)) PlotACC(acc$ACC, startDates) } -\references{ -Joliffe and Stephenson (2012). Forecast Verification: A Practitioner's Guide in Atmospheric Science. Wiley-Blackwell. -} \author{ History:\cr -0.1 - 2013-08 (V. Guemas, \email{virginie.guemas at bsc.es}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Formatting to CRAN\cr -1.1 - 2013-09 (C. Prodhomme, \email{chloe.prodhomme at bsc.es}) - optimization\cr -1.2 - 2014-08 (V. Guemas, \email{virginie.guemas at bsc.es}) - Bug-fixes : handling of NA & selection of domain + Simplification of code\cr -1.3.0 - 2014-08 (V. Guemas, \email{virginie.guemas at bsc.es}) - Boostrapping over members\cr -1.3.1 - 2014-09 (C. Prodhomme, chloe.prodhomme at bsc.es) - Add comments and minor style changes\cr -1.3.2 - 2015-02 (N. Manubens, nicolau.manubens at bsc.es) - Fixed ACC documentation and examples\cr + 0.1 - 2013-08 (V. Guemas, \email{virginie.guemas@bsc.es}) - Original code\cr + 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Formatting to CRAN\cr + 1.1 - 2013-09 (C. Prodhomme, \email{chloe.prodhomme@bsc.es}) - optimization\cr + 1.2 - 2014-08 (V. Guemas, \email{virginie.guemas@bsc.es}) - Bug-fixes: handling of NA & selection of domain + Simplification of code\cr + 1.3.0 - 2014-08 (V. Guemas, \email{virginie.guemas@bsc.es}) - Boostrapping over members\cr + 1.3.1 - 2014-09 (C. Prodhomme, \email{chloe.prodhomme@bsc.es}) - Add comments and minor style changes\cr + 1.3.2 - 2015-02 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Fixed ACC documentation and examples +} +\references{ +Joliffe and Stephenson (2012). Forecast Verification: A + Practitioner's Guide in Atmospheric Science. Wiley-Blackwell. } \keyword{datagen} + diff --git a/man/Alpha.Rd b/man/Alpha.Rd index 3cc1eb55fa3f42ab47856a9de965bdac9bfdda8f..c2350b2aec0fa3b35f5e7aed163d3c3325697d01 100644 --- a/man/Alpha.Rd +++ b/man/Alpha.Rd @@ -1,24 +1,45 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Alpha.R \name{Alpha} \alias{Alpha} \title{Estimates AutoCorrelation At Lag 1 following Guemas et al, BAMS, 2013b} -\description{This function, relying on the \code{FitAcfCoef()} function, estimates the autocorrelation at lag 1 of the xdata array following the method described in Guemas V., Auger L., Doblas-Reyes F., JAMC, 2013. After applying a linear detrending and/or a filtering of any frequency peak if requested, the sample autocorrelation is estimated.\cr Then the theoretical autocorrelation of an AR1 is fitted to the sample autocorrelation using the Cardano's formula (see \code{FitAcfCoef()}) to obtain the autocorrelation at lag 1. This method assumes xdata is an AR1 process. +\usage{ +Alpha(xdata, detrend = FALSE, filter = FALSE) } -\usage{Alpha(xdata, detrend = FALSE, filter = FALSE)} \arguments{ - \item{xdata}{Timeseries from which the autocorrelation at lag 1 is requested.} - \item{detrend}{TRUE applies a linear detrending to xdata prior to the estimation of the autocorrelation at lag 1.} - \item{filter}{TRUE applies a filtering of any frequency peak prior to the estimation of the autocorrelation at lag 1.} +\item{xdata}{Timeseries from which the autocorrelation at lag 1 is requested.} + +\item{detrend}{TRUE applies a linear detrending to xdata prior to the +estimation of the autocorrelation at lag 1.} + +\item{filter}{TRUE applies a filtering of any frequency peak prior to the +estimation of the autocorrelation at lag 1.} +} +\value{ +Autocorrelation at lag 1. +} +\description{ +This function, relying on the \code{FitAcfCoef()} function, estimates the +autocorrelation at lag 1 of the xdata array following the method described +in Guemas V., Auger L., Doblas-Reyes F., JAMC, 2013. After applying a linear +detrending and/or a filtering of any frequency peak if requested, the sample +autocorrelation is estimated.\cr +Then the theoretical autocorrelation of an AR1 is fitted to the sample +autocorrelation using the Cardano's formula (see \code{FitAcfCoef()}) to +obtain the autocorrelation at lag 1. This method assumes xdata is an AR1 +process. } -\value{Autocorrelation at lag 1} \examples{ # Load sample data as in Load() example: example(Load) alpha <- Alpha(sampleData$mod[1, 1, , 1]) print(alpha) + } \author{ History:\cr -0.1 - 2012-06 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN + 0.1 - 2012-06 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr + 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{datagen} + diff --git a/man/AnimateMap.Rd b/man/AnimateMap.Rd index 3376a68521e14f85ac2ef3e7f8817bc521b72f36..85eb04a9609b368928d8ca85d4db9ce1870eb9be 100644 --- a/man/AnimateMap.Rd +++ b/man/AnimateMap.Rd @@ -1,184 +1,164 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/AnimateMap.R \name{AnimateMap} \alias{AnimateMap} \title{Animate Maps of Forecast/Observed Values or Scores Over Forecast Time} -\description{ -Create animations of maps in an equi-rectangular or stereographic projection, -showing the anomalies, the climatologies, the mean InterQuartile Range, -Maximum-Mininum, Standard Deviation, Median Absolute Deviation, the trends, -the RMSE, the correlation or the RMSSS, between modelled and observed data -along the forecast time (lead-time) for all input experiments and input -observational datasets. -} \usage{ -AnimateMap(var, lon, lat, toptitle = rep("", 11), sizetit = 1, units = "", - monini = 1, freq = 12, msk95lev = FALSE, brks = NULL, cols = NULL, - filled.continents = FALSE, lonmin = 0, lonmax = 360, latmin = -90, - latmax = 90, intlon = 20, intlat = 30, drawleg = TRUE, - subsampleg = 1, colNA='white', equi = TRUE, - fileout = c("output1_animvsltime.gif", "output2_animvsltime.gif", - "output3_animvsltime.gif"), ...) +AnimateMap(var, lon, lat, toptitle = rep("", 11), sizetit = 1, units = "", + monini = 1, freq = 12, msk95lev = FALSE, brks = NULL, cols = NULL, + filled.continents = FALSE, lonmin = 0, lonmax = 360, latmin = -90, + latmax = 90, intlon = 20, intlat = 30, drawleg = TRUE, + subsampleg = 1, colNA = "white", equi = TRUE, + fileout = c("output1_animvsltime.gif", "output2_animvsltime.gif", + "output3_animvsltime.gif"), ...) } \arguments{ - \item{var}{ -Matrix of dimensions (nltime, nlat, nlon) - or (nexp/nmod, nltime, nlat, nlon) - or (nexp/nmod, 3/4, nltime, nlat, nlon) - or (nexp/nmod, nobs, 3/4, nltime, nlat, nlon) - } - \item{lat}{ -Vector containing latitudes (degrees) - } - \item{lon}{ -Vector containing longtitudes (degrees) - } - \item{toptitle}{ -c('','', \dots) array of main title for each animation, optional. -If RMS, RMSSS, correlations: first exp with successive obs, then second exp -with successive obs, etc ... - } - \item{sizetit}{ -Multiplicative factor to increase title size, optional - } - \item{units}{ -Units, optional - } - \item{monini}{ -Starting month between 1 and 12. Default = 1 - } - \item{freq}{ -1 = yearly, 12 = monthly, 4 = seasonal ... - } - \item{msk95lev}{ -TRUE/FALSE grid points with dots if 95\% significance level reached. -Default = FALSE - } - \item{brks}{ -Limits of colour levels, optional. For example: -seq(min(var), max(var), (max(var) - min(var)) / 10) - } - \item{cols}{ -Vector of colours of length(brks) - 1, optional. - } - \item{filled.continents}{ -Continents filled in grey (TRUE) or represented by a black line (FALSE). -Default = TRUE. -Filling unavailable if crossing Greenwich and equi = TRUE. -Filling unavailable if square = FALSE and equi = TRUE. - } - \item{lonmin}{ -Westward limit of the domain to plot (> 0 or < 0). -Default : 0 degrees - } - \item{lonmax}{ -Eastward limit of the domain to plot (> 0 or < 0). -lonmax > lonmin. Default : 360 degrees - } - \item{latmin}{ -Southward limit of the domain to plot. Default : -90 degrees - } - \item{latmax}{ -Northward limit of the domain to plot. Default : 90 degrees - } - \item{intlat}{ -Interval between latitude ticks on y-axis for equi = TRUE -or between latitude circles for equi = FALSE. Default = 30 degrees. - } - \item{intlon}{ -Interval between longitude ticks on x-axis. Default = 20 degrees. - } - \item{drawleg}{ -Draw a colorbar. Can be FALSE only if square = FALSE or equi = FALSE. -Default = TRUE - } - \item{subsampleg}{ -Supsampling factor of the interval between ticks on colorbar. -Default = 1 = every colour level. - } - \item{colNA}{ -Color used to represent NA. Default = 'white' - } - \item{equi}{ -TRUE/FALSE == cylindrical equidistant/stereographic projection. -Default: TRUE - } - \item{fileout}{ -c('', '', \dots) array of output file name for each animation. -If RMS, RMSSS, correlations : first exp with successive obs, then second exp -with successive obs, etc ... - } - \item{...}{ -Arguments to be passed to the method. Only accepts the following -graphical parameters: - -adj ann ask bty cex cex.axis cex.lab cex.main cex.sub cin col.axis col.lab -col.main col.sub cra crt csi cxy err family fg fig font font.axis font.lab -font.main font.sub las lheight ljoin lmitre lty lwd mai mar mex mfcol mfrow mfg -mgp mkh oma omd omi page pch plt pty smo srt tck tcl usr xaxp xaxs xaxt xlog -xpd yaxp yaxs yaxt ylbias ylog - -For more information about the parameters see `par`. - } +\item{var}{Matrix of dimensions (nltime, nlat, nlon) or +(nexp/nmod, nltime, nlat, nlon) or (nexp/nmod, 3/4, nltime, nlat, nlon) or +(nexp/nmod, nobs, 3/4, nltime, nlat, nlon).} + +\item{lon}{Vector containing longtitudes (degrees).} + +\item{lat}{Vector containing latitudes (degrees).} + +\item{toptitle}{c('','', \dots) array of main title for each animation, +optional. If RMS, RMSSS, correlations: first exp with successive obs, then +second exp with successive obs, etc ...} + +\item{sizetit}{Multiplicative factor to increase title size, optional.} + +\item{units}{Units, optional.} + +\item{monini}{Starting month between 1 and 12. Default = 1.} + +\item{freq}{1 = yearly, 12 = monthly, 4 = seasonal ...} + +\item{msk95lev}{TRUE/FALSE grid points with dots if 95\% significance level +reached. Default = FALSE.} + +\item{brks}{Limits of colour levels, optional. For example: +seq(min(var), max(var), (max(var) - min(var)) / 10).} + +\item{cols}{Vector of colours of length(brks) - 1, optional.} + +\item{filled.continents}{Continents filled in grey (TRUE) or represented by +a black line (FALSE). Default = TRUE. Filling unavailable if crossing +Greenwich and equi = TRUE. Filling unavailable if square = FALSE and +equi = TRUE.} + +\item{lonmin}{Westward limit of the domain to plot (> 0 or < 0). +Default : 0 degrees.} + +\item{lonmax}{Eastward limit of the domain to plot (> 0 or < 0). +lonmax > lonmin. Default : 360 degrees.} + +\item{latmin}{Southward limit of the domain to plot. Default : -90 degrees.} + +\item{latmax}{Northward limit of the domain to plot. Default : 90 degrees.} + +\item{intlon}{Interval between longitude ticks on x-axis. +Default = 20 degrees.} + +\item{intlat}{Interval between latitude ticks on y-axis for equi = TRUE or +between latitude circles for equi = FALSE. Default = 30 degrees.} + +\item{drawleg}{Draw a colorbar. Can be FALSE only if square = FALSE or +equi = FALSE. Default = TRUE.} + +\item{subsampleg}{Supsampling factor of the interval between ticks on +colorbar. Default = 1 = every colour level.} + +\item{colNA}{Color used to represent NA. Default = 'white'.} + +\item{equi}{TRUE/FALSE == cylindrical equidistant/stereographic projection. +Default: TRUE.} + +\item{fileout}{c('', '', \dots) array of output file name for each animation. + If RMS, RMSSS, correlations : first exp with successive obs, then second +exp with successive obs, etc ...} + +\item{...}{Arguments to be passed to the method. Only accepts the following +graphical parameters:\cr +adj ann ask bty cex cex.axis cex.lab cex.main cex.sub + cin col.axis col.lab col.main col.sub cra crt csi cxy err family fg fig +font font.axis font.lab font.main font.sub las lheight ljoin lmitre lty +lwd mai mar mex mfcol mfrow mfg mgp mkh oma omd omi page pch plt pty smo +srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog. \cr +For more information about the parameters see `par`.} +} +\description{ +Create animations of maps in an equi-rectangular or stereographic +projection, showing the anomalies, the climatologies, the mean InterQuartile +Range, Maximum-Mininum, Standard Deviation, Median Absolute Deviation, +the trends, the RMSE, the correlation or the RMSSS, between modelled and +observed data along the forecast time (lead-time) for all input experiments +and input observational datasets. } \details{ Examples of input: - -1- Outputs from clim (exp, obs, memb = FALSE): - (nmod, nltime, nlat, nlon) - or (nobs, nltime, nlat, nlon) - -2- Model output from load/ano/smoothing: - (nmod, nmemb, sdate, nltime, nlat, nlon) -then passed through spread(var, posdim = 2, narm = TRUE) - & mean1dim(var, posdim = 3, narm = TRUE) -or through trend(mean1dim(var, 2), posTR = 2): - (nmod, 3, nltime, nlat, nlon) -animates average along start dates of IQR/MaxMin/SD/MAD across members -or trends of the ensemble-mean computed accross the start dates. - -3- model and observed output from load/ano/smoothing: - (nmod, nmemb, sdate, nltime, nlat, nlon) - & (nobs, nmemb, sdate, nltime, nlat, nlon) -then averaged along members mean1dim(var_exp/var_obs, posdim = 2): - (nmod, sdate, nltime, nlat, nlon) - (nobs, sdate, nltime, nlat, nlon) -then passed through corr(exp, obs, posloop = 1, poscor = 2) - or RMS(exp, obs, posloop = 1, posRMS = 2): - (nmod, nobs, 3, nltime, nlat, nlon) -animates correlations or RMS between each exp & each obs against leadtime. +\enumerate{ + \item{ + Outputs from clim (exp, obs, memb = FALSE): + (nmod, nltime, nlat, nlon) + or (nobs, nltime, nlat, nlon) + } + \item{ + Model output from load/ano/smoothing: + (nmod, nmemb, sdate, nltime, nlat, nlon) + then passed through spread(var, posdim = 2, narm = TRUE) + & mean1dim(var, posdim = 3, narm = TRUE) + or through trend(mean1dim(var, 2), posTR = 2): + (nmod, 3, nltime, nlat, nlon) + animates average along start dates of IQR/MaxMin/SD/MAD across members + or trends of the ensemble-mean computed accross the start dates. + } + \item{ + model and observed output from load/ano/smoothing: + (nmod, nmemb, sdate, nltime, nlat, nlon) + & (nobs, nmemb, sdate, nltime, nlat, nlon) + then averaged along members mean1dim(var_exp/var_obs, posdim = 2): + (nmod, sdate, nltime, nlat, nlon) + (nobs, sdate, nltime, nlat, nlon) + then passed through corr(exp, obs, posloop = 1, poscor = 2) + or RMS(exp, obs, posloop = 1, posRMS = 2): + (nmod, nobs, 3, nltime, nlat, nlon) + animates correlations or RMS between each exp & each obs against leadtime. + } +} } \examples{ # See ?Load for explanations on the first part of this example - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') expA <- list(name = 'experiment', path = file.path(data_path, - 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', - '$VAR_NAME$_$START_DATE$.nc')) + 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', + '$VAR_NAME$_$START_DATE$.nc')) obsX <- list(name = 'observation', path = file.path(data_path, - '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', - '$VAR_NAME$_$YEAR$$MONTH$.nc')) + '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', + '$VAR_NAME$_$YEAR$$MONTH$.nc')) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(expA), list(obsX), startDates, - output = 'lonlat', latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } - \dontshow{ + output = 'lonlat', latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } + \dontshow{ startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - output = 'lonlat', - latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } + c('observation'), startDates, + output = 'lonlat', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } clim <- Clim(sampleData$mod, sampleData$obs, memb = FALSE) - \dontrun{ + \dontrun{ AnimateMap(clim$clim_exp, sampleData$lon, sampleData$lat, - toptitle = "climatology of decadal prediction", sizetit = 1, - units = "degree", brks = seq(270, 300, 3), monini = 11, freq = 12, - msk95lev = FALSE, filled.continents = TRUE, intlon = 10, intlat = 10, - fileout = 'clim_dec.gif') - } + toptitle = "climatology of decadal prediction", sizetit = 1, + units = "degree", brks = seq(270, 300, 3), monini = 11, freq = 12, + msk95lev = FALSE, filled.continents = TRUE, intlon = 10, intlat = 10, + fileout = 'clim_dec.gif') + } ano_exp <- Ano(sampleData$mod, clim$clim_exp) ano_obs <- Ano(sampleData$obs, clim$clim_obs) leadtimes_dimension <- 4 @@ -186,29 +166,30 @@ initial_month <- 11 mean_start_month <- 1 mean_stop_month <- 12 season_means_mod <- Season(ano_exp, leadtimes_dimension, initial_month, - mean_start_month, mean_stop_month) + mean_start_month, mean_stop_month) season_means_obs <- Season(ano_obs, leadtimes_dimension, initial_month, - mean_start_month, mean_stop_month) - \dontrun{ + mean_start_month, mean_stop_month) + \dontrun{ AnimateMap(Mean1Dim(season_means_mod, 2)[1, 1, , , ], sampleData$lon, - sampleData$lat, toptitle = "Annual anomalies 1985 of decadal prediction", - sizetit = 1, units = "degree", monini = 1, freq = 1, msk95lev = FALSE, - brks = seq(-0.5, 0.5, 0.1), intlon = 10, intlat = 10, - filled.continents = TRUE, fileout = 'annual_means_dec.gif') - } + sampleData$lat, toptitle = "Annual anomalies 1985 of decadal prediction", + sizetit = 1, units = "degree", monini = 1, freq = 1, msk95lev = FALSE, + brks = seq(-0.5, 0.5, 0.1), intlon = 10, intlat = 10, + filled.continents = TRUE, fileout = 'annual_means_dec.gif') + } dim_to_mean <- 2 # Mean along members rms <- RMS(Mean1Dim(season_means_mod, dim_to_mean), - Mean1Dim(season_means_obs, dim_to_mean)) + Mean1Dim(season_means_obs, dim_to_mean)) AnimateMap(rms, sampleData$lon, sampleData$lat, toptitle = - "RMSE decadal prediction", sizetit = 1, units = "degree", - monini = 1, freq = 1, msk95lev = FALSE, brks = seq(0, 0.8, 0.08), - intlon = 10, intlat = 10, filled.continents = TRUE, - fileout = 'rmse_dec.gif') + "RMSE decadal prediction", sizetit = 1, units = "degree", + monini = 1, freq = 1, msk95lev = FALSE, brks = seq(0, 0.8, 0.08), + intlon = 10, intlat = 10, filled.continents = TRUE, + fileout = 'rmse_dec.gif') } \author{ History:\cr -1.0 - 2012-04 (V. Guemas, \email{virginie.guemas at bsc.es}) - Original code\cr -1.1 - 2014-04 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Formatting to CRAN\cr -1.2 - 2015-05 (V. Guemas, \email{virginie.guemas at bsc.es}) - Use of PlotEquiMap and PlotStereoMap\cr + 1.0 - 2012-04 (V. Guemas, \email{virginie.guemas@bsc.es}) - Original code\cr + 1.1 - 2014-04 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Formatting to CRAN\cr + 1.2 - 2015-05 (V. Guemas, \email{virginie.guemas@bsc.es}) - Use of PlotEquiMap and PlotStereoMap } \keyword{dynamic} + diff --git a/man/Ano.Rd b/man/Ano.Rd index 9614813f26df4c4126189c73111604ede3d0a69d..a2deb37384718231f72d51fdbe0c1602b846903d 100644 --- a/man/Ano.Rd +++ b/man/Ano.Rd @@ -1,32 +1,32 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Ano.R \name{Ano} \alias{Ano} \title{Computes Forecast or Observed Anomalies} -\description{ -This function computes anomalies from any experimental or observational matrix output from \code{Load()} and their climatologies output from \code{Clim()}. +\usage{ +Ano(var, clim) } -\usage{Ano(var, clim)} \arguments{ - \item{var}{ -Model or observational data:\cr - c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltime) up to\cr - c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon) - } - \item{clim}{ -Climatologies from clim:\cr - c(nmod/nexp/nobs, nltime) up to\cr - c(nmod/nexp/nobs, nltime, nlevel, nlat, nlon)\cr -or\cr - c(nmod/nexp/nobs, nmemb/nparam, nltime) up to\cr - c(nmod/nexp/nobs, nmemb/nparam, nltime, nlevel, nlat, nlon)\cr -or\cr - c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltime) up to\cr - c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon)\cr -depending on the options provided to \code{Clim()} - } +\item{var}{Model or observational data:\cr +c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltime) up to \cr +c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon)\cr} + +\item{clim}{Climatologies from clim: c(nmod/nexp/nobs, nltime) \cr +up to c(nmod/nexp/nobs, nltime, nlevel, nlat, nlon) or \cr +c(nmod/nexp/nobs, nmemb/nparam, nltime) up to \cr +c(nmod/nexp/nobs, nmemb/nparam, nltime, nlevel, nlat, nlon) or \cr +c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltime) up to \cr +c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon) \cr +depending on the options provided to \code{Clim()}.} } \value{ Array with same dimensions as 'var'. } +\description{ +This function computes anomalies from any experimental or observational +matrix output from \code{Load()} and their climatologies output from +\code{Clim()}. +} \examples{ # Load sample data as in Load() example: example(Load) @@ -38,12 +38,13 @@ dim_to_smooth <- 4 # Smooth along lead-times smooth_ano_exp <- Smoothing(ano_exp, runmean_nb_months, dim_to_smooth) smooth_ano_obs <- Smoothing(ano_obs, runmean_nb_months, dim_to_smooth) PlotAno(smooth_ano_exp, smooth_ano_obs, startDates, - toptitle = paste('smoothed anomalies'), ytitle = c('K', 'K', 'K'), - legends = 'ERSST', biglab = FALSE, fileout = 'tos_ano.eps') + toptitle = paste('smoothed anomalies'), ytitle = c('K', 'K', 'K'), + legends = 'ERSST', biglab = FALSE, fileout = 'tos_ano.eps') } \author{ History:\cr -0.1 - 2012-03 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to R CRAN + 0.1 - 2012-03 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr + 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to R CRAN } \keyword{datagen} + diff --git a/man/Ano_CrossValid.Rd b/man/Ano_CrossValid.Rd index 7e488ca2e8a7ce923dadadb8957e5f70f18f754c..bb2be436f59096d452240bae72da7698805de64c 100644 --- a/man/Ano_CrossValid.Rd +++ b/man/Ano_CrossValid.Rd @@ -1,43 +1,44 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Ano_CrossValid.R \name{Ano_CrossValid} \alias{Ano_CrossValid} \title{Computes Anomalies In Cross-Validation Mode} -\description{ -Computes the anomalies from the arrays of the experimental and observational data output from \code{load()} by subtracting the climatologies computed with a cross-validation technique and a per-pair method. -} \usage{ Ano_CrossValid(var_exp, var_obs, memb = TRUE) } \arguments{ - \item{var_exp}{ -Model data:\cr - c(nmod/nexp, nmemb/nparam, nsdates, nltime) up to\cr - c(nmod/nexp, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon) - } - \item{var_obs}{ -Observational data:\cr - c(nobs, nmemb, nsdates, nltime) up to\cr - c(nobs, nmemb, nsdates, nltime, nlevel, nlat, nlon) - } - \item{memb}{ -memb: TRUE/FALSE (1 climatology for each member/1 climatology averaging all the members).\cr -Default = TRUE. - } +\item{var_exp}{Model data:\cr +c(nmod/nexp, nmemb/nparam, nsdates, nltime) up to \cr + c(nmod/nexp, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon).} + +\item{var_obs}{Observational data: \cr +c(nobs, nmemb, nsdates, nltime) up to \cr + c(nobs, nmemb, nsdates, nltime, nlevel, nlat, nlon).} + +\item{memb}{TRUE/FALSE (1 climatology for each member/1 climatology +averaging all the members). Default = TRUE.} } \value{ - \item{$ano_exp}{Matrix with same dimensions as var_exp} - \item{$ano_obs}{Matrix with same dimensions as var_obs} +\item{$ano_exp}{Matrix with same dimensions as var_exp} + \item{$ano_obs}{Matrix with same dimensions as var_obs} +} +\description{ +Computes the anomalies from the arrays of the experimental and observational +data output from \code{load()} by subtracting the climatologies computed +with a cross-validation technique and a per-pair method. } \examples{ # Load sample data as in Load() example: example(Load) anomalies <- Ano_CrossValid(sampleData$mod, sampleData$obs) PlotAno(anomalies$ano_exp, anomalies$ano_obs, startDates, - toptitle = paste('anomalies'), ytitle = c('K', 'K', 'K'), - legends = 'ERSST', biglab = FALSE, fileout = 'tos_ano_crossvalid.eps') + toptitle = paste('anomalies'), ytitle = c('K', 'K', 'K'), + legends = 'ERSST', biglab = FALSE, fileout = 'tos_ano_crossvalid.eps') } \author{ History:\cr -0.1 - 2011-12 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN + 0.1 - 2011-12 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr + 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{datagen} + diff --git a/man/ArrayToNetCDF.Rd b/man/ArrayToNetCDF.Rd index fcfb77005610e6eb13fa044e3b0c49e2a158c876..77cbfaf8ccf98c0c4ce48c2ddefc4cd1037e0bd6 100644 --- a/man/ArrayToNetCDF.Rd +++ b/man/ArrayToNetCDF.Rd @@ -1,53 +1,83 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ArrayToNetCDF.R \name{ArrayToNetCDF} \alias{ArrayToNetCDF} \title{Save multidimensional R arrays into NetCDF files} -\description{This function takes as input one or a list of multidimensional R arrays and stores them in a NetCDF file, using the \code{ncdf4} package. The full path and name of the resulting file must be specified. Metadata can be attached to the arrays and propagated into the NetCDF file in 3 possible ways:\cr - \itemize{ - \item{Via the list names if a list of arrays is provided:}{Each name in the input list, corresponding to one multidimensional array, will be interpreted as the name of the variable it contains.\cr -E.g:\cr - \code{ -ArrayToNetCDF(arrays = list(temperature = array(1:9, c(3, 3))), - file_path = 'example.nc') - } - } - \item{Via the dimension names of each provided array:}{The dimension names of each of the provided arrays will be interpreted as names for the dimensions of the NetCDF files. Read further for special dimension names that will trigger special behaviours, such as 'time' and 'var'.\cr -E.g:\cr - \code{ -temperature <- array(rnorm(100 * 50 * 10), dim = c(100, 50, 10)) -names(dim(temperature)) <- c('longitude', 'latitude', 'time') -ArrayToNetCDF(list(temperature = temperature), file_path = 'example.nc') - } - } - \item{Via the attribute 'variables' of each provided array:}{The arrays can be provided with metadata in an attribute named 'variables', which is expected to be a named list of named lists, where the names of the container list are the names of the variables present in the provided array, and where each sub-list contains metadata for each of the variables. The attribute names and values supported in the sub-lists must follow the same format the package \code{ncdf4} uses to represent the NetCDF file headers.\cr -E.g:\cr - \code{ -a <- array(1:400, dim = c(5, 10, 4, 2)) -metadata <- list( - tos = list(addOffset = 100, - scaleFact = 10, - dim = list(list(name = 'time', - unlim = FALSE))) - ) -attr(a, 'variables') <- metadata -names(dim(a)) <- c('lat', 'lon', 'time', 'var') -ArrayToNetCDF(a, 'tmp.nc') - } - } - } -The special dimension names are 'var'/'variable' and 'time'.\cr -If a dimension is named 'var' or 'variable', \code{ArrayToNetCDF} will interpret each array entry along such dimension corresponds to a separate new variable, hence will create a new variable inside the NetCDF file and will use it to store all the data in the provided array for the corresponding entry along the 'var'/'variable' dimension.\cr -If a dimension is named 'time', by default it will be interpreted and built as an unlimited dimension. The 'time' dimension must be the last dimension of the array (the right-most). If a 'var'/'variable' dimension is present, the 'time' dimension can be also placed on its left (i.e. the one before the last dimension). The default behaviour of creating the 'time' as unlimited dimension can be disabled by setting manually the attribute \code{unlim = FALSE}, as shown in the previous example. -} \usage{ ArrayToNetCDF(arrays, file_path) } \arguments{ - \item{arrays}{One or a list of multidimensional data arrays. The list can be provided with names, which will be interpreted as variable names. The arrays can be provided with dimension names. The arrays can be provided with metadata in the attribute 'variables' (read section Description for details).} - \item{file_path}{Path and name of the NetCDF file to be created.} +\item{arrays}{One or a list of multidimensional data arrays. The list can be +provided with names, which will be interpreted as variable names. The +arrays can be provided with dimension names. The arrays can be provided +with metadata in the attribute 'variables' (read section Description for +details).} + +\item{file_path}{Path and name of the NetCDF file to be created.} +} +\value{ +This function returns NULL. +} +\description{ +This function takes as input one or a list of multidimensional R arrays and +stores them in a NetCDF file, using the \code{ncdf4} package. The full path +and name of the resulting file must be specified. Metadata can be attached +to the arrays and propagated into the NetCDF file in 3 possible ways: +\itemize{ + \item{ + Via the list names if a list of arrays is provided: Each name in + the input list, corresponding to one multidimensional array, will be + interpreted as the name of the variable it contains.\cr + E.g:\cr + \code{ArrayToNetCDF(arrays = list(temperature = array(1:9, c(3, 3))),}\cr + \code{ file_path = 'example.nc')} + } + \item{ + Via the dimension names of each provided array: The dimension names + of each of the provided arrays will be interpreted as names for the + dimensions of the NetCDF files. Read further for special dimension names + that will trigger special behaviours, such as 'time' and 'var'.\cr + E.g:\cr + \code{temperature <- array(rnorm(100 * 50 * 10), dim = c(100, 50, 10))}\cr + \code{names(dim(temperature)) <- c('longitude', 'latitude', 'time')}\cr + \code{ArrayToNetCDF(list(temperature = temperature), file_path = 'example.nc')} + } + \item{ + Via the attribute 'variables' of each provided array: The arrays can + be provided with metadata in an attribute named 'variables', which is + expected to be a named list of named lists, where the names of the + container list are the names of the variables present in the provided + array, and where each sub-list contains metadata for each of the variables. + The attribute names and values supported in the sub-lists must follow the + same format the package \code{ncdf4} uses to represent the NetCDF + file headers.\cr + E.g:\cr + \code{a <- array(1:400, dim = c(5, 10, 4, 2))}\cr + \code{metadata <- list(tos = list(addOffset = 100,}\cr + \code{ scaleFact = 10,}\cr + \code{ dim = list(list(name = 'time',}\cr + \code{ unlim = FALSE))))}\cr + \code{attr(a, 'variables') <- metadata}\cr + \code{names(dim(a)) <- c('lat', 'lon', 'time', 'var')}\cr + \code{ArrayToNetCDF(a, 'tmp.nc')} + } +} +The special dimension names are 'var'/'variable' and 'time'.\cr +If a dimension is named 'var' or 'variable', \code{ArrayToNetCDF} will +interpret each array entry along such dimension corresponds to a separate +new variable, hence will create a new variable inside the NetCDF file and +will use it to store all the data in the provided array for the +corresponding entry along the 'var'/'variable' dimension.\cr +If a dimension is named 'time', by default it will be interpreted and built +as an unlimited dimension. The 'time' dimension must be the last dimension +of the array (the right-most). If a 'var'/'variable' dimension is present, +the 'time' dimension can be also placed on its left (i.e. the one before the +last dimension). The default behaviour of creating the 'time' as unlimited +dimension can be disabled by setting manually the attribute +\code{unlim = FALSE}, as shown in the previous example. } -\value{This function returns NULL} \examples{ - \dontrun{ + \dontrun{ # Minimal use case ArrayToNetCDF(array(1:9, c(3, 3)), 'tmp.nc') @@ -113,9 +143,9 @@ ArrayToNetCDF(list(a, b), 'tmp.nc') # attribute 'variables'. In this example the metadata is empty. a <- array(1:400, dim = c(5, 10, 4, 2)) metadata <- list( - tos = list(), - tas = list() - ) + tos = list(), + tas = list() + ) attr(a, 'variables') <- metadata names(dim(a)) <- c('lat', 'lon', 'time', 'var') ArrayToNetCDF(a, 'tmp.nc') @@ -123,9 +153,9 @@ ArrayToNetCDF(a, 'tmp.nc') # Variable names can be manually specified a <- array(1:400, dim = c(5, 10, 4, 2)) metadata <- list( - tos = list(name = 'name1'), - tas = list(name = 'name2') - ) + tos = list(name = 'name1'), + tas = list(name = 'name2') + ) attr(a, 'variables') <- metadata names(dim(a)) <- c('lat', 'lon', 'time', 'var') ArrayToNetCDF(a, 'tmp.nc') @@ -133,9 +163,9 @@ ArrayToNetCDF(a, 'tmp.nc') # Units can be specified a <- array(1:400, dim = c(5, 10, 4, 2)) metadata <- list( - tos = list(units = 'K'), - tas = list(units = 'K') - ) + tos = list(units = 'K'), + tas = list(units = 'K') + ) attr(a, 'variables') <- metadata names(dim(a)) <- c('lat', 'lon', 'time', 'var') ArrayToNetCDF(a, 'tmp.nc') @@ -143,11 +173,11 @@ ArrayToNetCDF(a, 'tmp.nc') # addOffset and scaleFactor can be specified a <- array(1:400, dim = c(5, 10, 4, 2)) metadata <- list( - tos = list(addOffset = 100, - scaleFact = 10), - tas = list(addOffset = 100, - scaleFact = 10) - ) + tos = list(addOffset = 100, + scaleFact = 10), + tas = list(addOffset = 100, + scaleFact = 10) + ) attr(a, 'variables') <- metadata names(dim(a)) <- c('lat', 'lon', 'time', 'var') ArrayToNetCDF(a, 'tmp.nc') @@ -155,15 +185,15 @@ ArrayToNetCDF(a, 'tmp.nc') # Unlimited dimensions can be manually created a <- array(1:400, dim = c(5, 10, 4, 2)) metadata <- list( - tos = list(addOffset = 100, - scaleFact = 10, - dim = list(list(name = 'unlimited', - unlim = TRUE))), - tas = list(addOffset = 100, - scaleFact = 10, - dim = list(list(name = 'unlimited', - unlim = TRUE))) - ) + tos = list(addOffset = 100, + scaleFact = 10, + dim = list(list(name = 'unlimited', + unlim = TRUE))), + tas = list(addOffset = 100, + scaleFact = 10, + dim = list(list(name = 'unlimited', + unlim = TRUE))) + ) attr(a, 'variables') <- metadata names(dim(a)) <- c('lat', 'lon', 'unlimited', 'var') ArrayToNetCDF(a, 'tmp.nc') @@ -171,15 +201,15 @@ ArrayToNetCDF(a, 'tmp.nc') # A 'time' dimension can be built without it necessarily being unlimited a <- array(1:400, dim = c(5, 10, 4, 2)) metadata <- list( - tos = list(addOffset = 100, - scaleFact = 10, - dim = list(list(name = 'time', - unlim = FALSE))), - tas = list(addOffset = 100, - scaleFact = 10, - dim = list(list(name = 'time', - unlim = FALSE))) - ) + tos = list(addOffset = 100, + scaleFact = 10, + dim = list(list(name = 'time', + unlim = FALSE))), + tas = list(addOffset = 100, + scaleFact = 10, + dim = list(list(name = 'time', + unlim = FALSE))) + ) attr(a, 'variables') <- metadata names(dim(a)) <- c('lat', 'lon', 'time', 'var') ArrayToNetCDF(a, 'tmp.nc') @@ -201,10 +231,11 @@ metadata <- list(lat = list(units = 'degrees_north')) attr(lat, 'variables') <- metadata names(dim(lat)) <- 'lat' ArrayToNetCDF(list(tos, lon, lat), 'tmp.nc') - } +} } \author{ History:\cr -0.0 - 2017-01 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Original code. + 0.0 - 2017-01 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Original code. } \keyword{datagen} + diff --git a/man/BrierScore.Rd b/man/BrierScore.Rd index e126729aadedd98349e231190b5aa5a9aac53c99..5094987c932a3215a59a86fbf896695aee3caacb 100644 --- a/man/BrierScore.Rd +++ b/man/BrierScore.Rd @@ -1,56 +1,57 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/BrierScore.R \name{BrierScore} -\alias{BrierScore} \alias{.BrierScore} -\title{ -Compute Brier Score And Its Decomposition And Brier Skill Score -} -\description{ -Computes the Brier score (BS) and the components of its standard decomposition as well with the two within-bin components described in Stephenson et al., (2008). It also returns the bias-corrected decomposition of the BS (Ferro and Fricker, 2012). BSS having the climatology as the reference forecast.\cr -\cr -.BrierScore provides the same functionality, but taking a matrix of ensemble members (exp) as input. -} +\alias{BrierScore} +\title{Compute Brier Score And Its Decomposition And Brier Skill Score} \usage{ BrierScore(obs, pred, thresholds = seq(0, 1, 0.1)) .BrierScore(exp, obs, thresholds = seq(0, 1, 0.1)) } \arguments{ - \item{obs}{ -Vector of binary observations (1 or 0) - } - \item{pred}{ -Vector of probablistic predictions with values in the range [0,1] - } - \item{thresholds}{ -Values used to bin the forecasts. By default the bins are {[0,0.1), [0.1, 0.2), ... [0.9, 1]} - } - \item{exp}{ -Matrix of predictions with values in the range [0,1] for the .BrierScore function - } +\item{obs}{Vector of binary observations (1 or 0).} + +\item{pred}{Vector of probablistic predictions with values in the range [0,1].} + +\item{thresholds}{Values used to bin the forecasts. By default the bins are +{[0,0.1), [0.1, 0.2), ... [0.9, 1]}.} + +\item{exp}{Matrix of predictions with values in the range [0,1] for the +.BrierScore function} } \value{ Both BrierScore and .Brier score provide the same outputs: - \itemize{ - \item{$rel}{standard reliability} - \item{$res}{standard resolution} - \item{$unc}{standard uncertainty} - \item{$bs}{Brier score} - \item{$bs_check_res}{rel-res+unc} - \item{$bss_res}{res-rel/unc} - \item{$gres}{generalized resolution} - \item{$bs_check_gres}{rel-gres+unc} - \item{$bss_gres}{gres-rel/unc} - \item{$rel_bias_corrected}{bias-corrected rel} - \item{$gres_bias_corrected}{bias-corrected gres} - \item{$unc_bias_corrected}{bias-corrected unc} - \item{$bss_bias_corrected}{gres_bias_corrected-rel_bias_corrected/unc_bias_corrected} - \item{$nk}{number of forecast in each bin} - \item{$fkbar}{average probability of each bin} - \item{$okbar}{relative frequency that the observed event occurred} - \item{$bins}{bins used} - \item{$pred}{values with which the forecasts are verified} - \item{$obs}{probability forecasts of the event} - } +\itemize{ + \item{$rel}{standard reliability} + \item{$res}{standard resolution} + \item{$unc}{standard uncertainty} + \item{$bs}{Brier score} + \item{$bs_check_res}{rel-res+unc} + \item{$bss_res}{res-rel/unc} + \item{$gres}{generalized resolution} + \item{$bs_check_gres}{rel-gres+unc} + \item{$bss_gres}{gres-rel/unc} + \item{$rel_bias_corrected}{bias-corrected rel} + \item{$gres_bias_corrected}{bias-corrected gres} + \item{$unc_bias_corrected}{bias-corrected unc} + \item{$bss_bias_corrected}{gres_bias_corrected-rel_bias_corrected/unc_bias_corrected} + \item{$nk}{number of forecast in each bin} + \item{$fkbar}{average probability of each bin} + \item{$okbar}{relative frequency that the observed event occurred} + \item{$bins}{bins used} + \item{$pred}{values with which the forecasts are verified} + \item{$obs}{probability forecasts of the event} +} +} +\description{ +Computes the Brier score (BS) and the components of its standard +decomposition as well with the two within-bin components described in +Stephenson et al., (2008). It also returns the bias-corrected decomposition +of the BS (Ferro and Fricker, 2012). BSS having the climatology as the +reference forecast. \cr\cr +.BrierScore provides the same functionality, but taking a matrix of ensemble +members (exp) as input. } \examples{ # Minimalist examples with BrierScore @@ -60,11 +61,11 @@ x <- BrierScore(b, a) x$bs - x$bs_check_res x$bs - x$bs_check_gres x$rel_bias_corrected - x$gres_bias_corrected + x$unc_bias_corrected - \dontrun{ + \dontrun{ a <- runif(10) b <- cbind(round(a),round(a)) # matrix containing 2 identical ensemble members... x2 <- BrierScore(a, b) - } + } # Example of BrierScore using UltimateBrier # See ?UltimateBrier for more information @@ -74,24 +75,27 @@ ano_exp <- Ano(sampleData$mod, clim$clim_exp) ano_obs <- Ano(sampleData$obs, clim$clim_obs) bs <- UltimateBrier(ano_exp, ano_obs, thr = c(1/3, 2/3)) - \dontrun{ + \dontrun{ # Example of .BrierScore with veriApply require(easyVerification) BrierScore2 <- s2dverification:::.BrierScore bins_ano_exp <- ProbBins(ano_exp, thr = c(1/3, 2/3), posdates = 3, posdim = 2) bins_ano_obs <- ProbBins(ano_obs, thr = c(1/3, 2/3), posdates = 3, posdim = 2) -bs2 <- veriApply("BrierScore2", bins_ano_exp, Mean1Dim(bins_ano_obs, 3), - tdim = 2, ensdim = 3) - } -} -\references{ -Wilks (2006) Statistical Methods in the Atmospheric Sciences.\cr -Stephenson et al. (2008). Two extra components in the Brier score decomposition. Weather and Forecasting, 23: 752-757.\cr -Ferro and Fricker (2012). A bias-corrected decomposition of the BS. Quarterly Journal of the Royal Meteorological Society, DOI: 10.1002/qj.1924.\cr +bs2 <- veriApply("BrierScore2", bins_ano_exp, Mean1Dim(bins_ano_ob,s 3), + tdim = 2, ensdim = 3) + } } \author{ History:\cr -0.1 - 2012-04 (L. Rodrigues, \email{lrodrigues at ic3.cat}) - Original code\cr -0.2 - 2017-02 (A. Hunter, \email{alasdair.hunter at bsc.es}) - Adapted to veriApply() + 0.1 - 2012-04 (L. Rodrigues, \email{lrodrigues@ic3.cat}) - Original code\cr + 0.2 - 2017-02 (A. Hunter, \email{alasdair.hunter@bsc.es}) - Adapted to veriApply() +} +\references{ +Wilks (2006) Statistical Methods in the Atmospheric Sciences.\cr +Stephenson et al. (2008). Two extra components in the Brier score decomposition. + Weather and Forecasting, 23: 752-757.\cr +Ferro and Fricker (2012). A bias-corrected decomposition of the BS. + Quarterly Journal of the Royal Meteorological Society, DOI: 10.1002/qj.1924. } \keyword{datagen} + diff --git a/man/CDORemap.Rd b/man/CDORemap.Rd index fa539dc6569f2b1540ba765b174b7e0edf854ce0..b2d5eaa318af16631bb7c813eccd2a635d9f8395 100644 --- a/man/CDORemap.Rd +++ b/man/CDORemap.Rd @@ -1,33 +1,92 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/CDORemap.R \name{CDORemap} \alias{CDORemap} \title{Interpolates arrays with longitude and latitude dimensions using CDO} -\description{This function takes as inputs a multidimensional array (optional), a vector or matrix of longitudes, a vector or matrix of latitudes, a destination grid specification, and the name of a method to be used to interpolate (one of those available in the 'remap' utility in CDO). The interpolated array is returned (if provided) together with the new longitudes and latitudes.\cr\cr -\code{CDORemap()} permutes by default the dimensions of the input array (if needed), splits it in chunks (CDO can work with data arrays of up to 4 dimensions), generates a file with the data of each chunk, interpolates it with CDO, reads it back into R and merges it into a result array. If no input array is provided, the longitude and latitude vectors will be transformed only. If the array is already on the desired destination grid, no transformation is performed (this behvaiour works only for lonlat and gaussian grids).\cr\cr -Any metadata attached to the input data array, longitudes or latitudes will be preserved or accordingly modified. -} \usage{ -CDORemap(data_array = NULL, lons, lats, grid, method, - avoid_writes = TRUE, crop = TRUE, - force_remap = FALSE, write_dir = tempdir()) +CDORemap(data_array = NULL, lons, lats, grid, method, avoid_writes = TRUE, + crop = TRUE, force_remap = FALSE, write_dir = tempdir()) } \arguments{ - \item{data_array}{Multidimensional numeric array to be interpolated. If provided, it must have at least a longitude and a latitude dimensions, identified by the array dimension names. The names for these dimensions must be one of the recognized by s2dverification (can be checked with \code{s2dverification:::.KnownLonNames()} and \code{s2dverification:::.KnownLatNames()}).} - \item{lons}{Numeric vector or array of longitudes of the centers of the grid cells. Its size must match the size of the longitude/latitude dimensions of the input array.} - \item{lats}{Numeric vector or array of latitudes of the centers of the grid cells. Its size must match the size of the longitude/latitude dimensions of the input array.} - \item{grid}{Character string specifying either a name of a target grid (recognized by CDO; e.g.: 'r256x128', 't106grid') or a path to another NetCDF file which to read the target grid from (a single grid must be defined in such file).} - \item{method}{Character string specifying an interpolation method (recognized by CDO; e.g.: 'con', 'bil', 'bic', 'dis'). The following long names are also supported: 'conservative', 'bilinear', 'bicubic' and 'distance-weighted'.} - \item{avoid_writes}{The step of permutation is needed when the input array has more than 3 dimensions and none of the longitude or latitude dimensions in the right-most position (CDO would not accept it without permuting previously). This step, executed by default when needed, can be avoided for the price of writing more intermediate files (whis usually is unconvenient) by setting the parameter \code{avoid_writes = TRUE}.} - \item{crop}{Whether to crop the data after interpolation with 'cdo sellonlatbox' (TRUE) or to extend interpolated data to the whole world as CDO does by default (FALSE). If \code{crop = TRUE} then the longitude and latitude borders which to crop at are taken as the limits of the cells at the borders ('lons' and 'lats' are perceived as cell centers), i.e. the resulting array will contain data that covers the same area as the input array. This is equivalent to specifying \code{crop = 'preserve'}, i.e. preserving area. If \code{crop = 'tight'} then the borders which to crop at are taken as the minimum and maximum cell centers in 'lons' and 'lats', i.e. the area covered by the resulting array may be smaller if interpolating from a coarse grid to a fine grid. The parameter 'crop' also accepts a numeric vector of custom borders which to crop at: c(western border, eastern border, southern border, northern border). } - \item{force_remap}{Whether to force remapping, even if the input data array is already on the target grid.} - \item{write_dir}{Path to the directory where to create the intermediate files for CDO to work. By default, the R session temporary directory is used (\code{tempdir()}).} +\item{data_array}{Multidimensional numeric array to be interpolated. If +provided, it must have at least a longitude and a latitude dimensions, +identified by the array dimension names. The names for these dimensions +must be one of the recognized by s2dverification (can be checked with +\code{s2dverification:::.KnownLonNames()} and +\code{s2dverification:::.KnownLatNames()}).} + +\item{lons}{Numeric vector or array of longitudes of the centers of the grid +cells. Its size must match the size of the longitude/latitude dimensions +of the input array.} + +\item{lats}{Numeric vector or array of latitudes of the centers of the grid +cells. Its size must match the size of the longitude/latitude dimensions +of the input array.} + +\item{grid}{Character string specifying either a name of a target grid +(recognized by CDO; e.g.: 'r256x128', 't106grid') or a path to another +NetCDF file which to read the target grid from (a single grid must be +defined in such file).} + +\item{method}{Character string specifying an interpolation method +(recognized by CDO; e.g.: 'con', 'bil', 'bic', 'dis'). The following +long names are also supported: 'conservative', 'bilinear', 'bicubic' and +'distance-weighted'.} + +\item{avoid_writes}{The step of permutation is needed when the input array +has more than 3 dimensions and none of the longitude or latitude dimensions + in the right-most position (CDO would not accept it without permuting +previously). This step, executed by default when needed, can be avoided +for the price of writing more intermediate files (whis usually is +unconvenient) by setting the parameter \code{avoid_writes = TRUE}.} + +\item{crop}{Whether to crop the data after interpolation with +'cdo sellonlatbox' (TRUE) or to extend interpolated data to the whole +world as CDO does by default (FALSE). If \code{crop = TRUE} then the +longitude and latitude borders which to crop at are taken as the limits of +the cells at the borders ('lons' and 'lats' are perceived as cell centers), +i.e. the resulting array will contain data that covers the same area as +the input array. This is equivalent to specifying \code{crop = 'preserve'}, +i.e. preserving area. If \code{crop = 'tight'} then the borders which to +crop at are taken as the minimum and maximum cell centers in 'lons' and +'lats', i.e. the area covered by the resulting array may be smaller if +interpolating from a coarse grid to a fine grid. The parameter 'crop' also +accepts a numeric vector of custom borders which to crop at: +c(western border, eastern border, southern border, northern border).} + +\item{force_remap}{Whether to force remapping, even if the input data array +is already on the target grid.} + +\item{write_dir}{Path to the directory where to create the intermediate +files for CDO to work. By default, the R session temporary directory is +used (\code{tempdir()}).} } -\value{A list with the following components:\cr - \item{'data_array'}{The interpolated data array (if an input array is provided at all, NULL otherwise).} - \item{'lons'}{The longitudes of the data on the destination grid.} - \item{'lats'}{The latitudes of the data on the destination grid.} +\value{ +A list with the following components: + \item{'data_array'}{The interpolated data array (if an input array + is provided at all, NULL otherwise).} + \item{'lons'}{The longitudes of the data on the destination grid.} + \item{'lats'}{The latitudes of the data on the destination grid.} +} +\description{ +This function takes as inputs a multidimensional array (optional), a vector +or matrix of longitudes, a vector or matrix of latitudes, a destination grid +specification, and the name of a method to be used to interpolate (one of +those available in the 'remap' utility in CDO). The interpolated array is +returned (if provided) together with the new longitudes and latitudes.\cr\cr +\code{CDORemap()} permutes by default the dimensions of the input array (if +needed), splits it in chunks (CDO can work with data arrays of up to 4 +dimensions), generates a file with the data of each chunk, interpolates it +with CDO, reads it back into R and merges it into a result array. If no +input array is provided, the longitude and latitude vectors will be +transformed only. If the array is already on the desired destination grid, +no transformation is performed (this behvaiour works only for lonlat and +gaussian grids). \cr\cr +Any metadata attached to the input data array, longitudes or latitudes will +be preserved or accordingly modified. } \examples{ - \dontrun{ + \dontrun{ # Interpolating only vectors of longitudes and latitudes lon <- seq(0, 360 - 360/50, length.out = 50) lat <- seq(-90, 90, length.out = 25) @@ -51,10 +110,10 @@ lat <- seq(-90, 90, length.out = 25) metadata <- list(lat = list(units = 'degrees_north')) attr(lat, 'variables') <- metadata metadata <- list(tas = list(dim = list(lat = list(len = 25, - vals = lat), - lon = list(len = 50, - vals = lon) - ))) + vals = lat), + lon = list(len = 50, + vals = lon) + ))) attr(tas, 'variables') <- metadata tas2 <- CDORemap(tas, lon, lat, 't170grid', 'bil', TRUE) @@ -62,7 +121,7 @@ tas2 <- CDORemap(tas, lon, lat, 't170grid', 'bil', TRUE) num_lats <- 25 num_lons <- 50 tas <- array(1:(10*num_lats*10*num_lons*10), - dim = c(10, num_lats, 10, num_lons, 10)) + dim = c(10, num_lats, 10, num_lons, 10)) names(dim(tas)) <- c('a', 'lat', 'b', 'lon', 'c') lon <- seq(0, 360 - 360/num_lons, length.out = num_lons) metadata <- list(lon = list(units = 'degrees_east')) @@ -71,13 +130,13 @@ lat <- seq(-90, 90, length.out = num_lats) metadata <- list(lat = list(units = 'degrees_north')) attr(lat, 'variables') <- metadata metadata <- list(tas = list(dim = list(a = list(), - lat = list(len = num_lats, - vals = lat), - b = list(), - lon = list(len = num_lons, - vals = lon), - c = list() - ))) + lat = list(len = num_lats, + vals = lat), + b = list(), + lon = list(len = num_lons, + vals = lon), + c = list() + ))) attr(tas, 'variables') <- metadata tas2 <- CDORemap(tas, lon, lat, 't17grid', 'bil', TRUE) # The step of permutation can be avoided but more intermediate file writes @@ -90,7 +149,7 @@ tas2 <- CDORemap(tas, lon, lat, 't17grid', 'bil', FALSE) num_lats <- 25 num_lons <- 50 tas <- array(1:(10*num_lats*10*num_lons*10), - dim = c(10, num_lats, 10, num_lons)) + dim = c(10, num_lats, 10, num_lons)) names(dim(tas)) <- c('a', 'lat', 'b', 'lon') lon <- seq(0, 360 - 360/num_lons, length.out = num_lons) metadata <- list(lon = list(units = 'degrees_east')) @@ -99,12 +158,12 @@ lat <- seq(-90, 90, length.out = num_lats) metadata <- list(lat = list(units = 'degrees_north')) attr(lat, 'variables') <- metadata metadata <- list(tas = list(dim = list(a = list(), - lat = list(len = num_lats, - vals = lat), - b = list(), - lon = list(len = num_lons, - vals = lon) - ))) + lat = list(len = num_lats, + vals = lat), + b = list(), + lon = list(len = num_lons, + vals = lon) + ))) attr(tas, 'variables') <- metadata tas2 <- CDORemap(tas, lon, lat, 't17grid', 'bil', TRUE) tas2 <- CDORemap(tas, lon, lat, 't17grid', 'bil', FALSE) @@ -115,12 +174,12 @@ num_lons <- 50 tas <- array(1:(1*num_lats*num_lons), dim = c(num_lats, num_lons)) names(dim(tas)) <- c('y', 'x') lon <- array(seq(0, 360 - 360/num_lons, length.out = num_lons), - dim = c(num_lons, num_lats)) + dim = c(num_lons, num_lats)) metadata <- list(lon = list(units = 'degrees_east')) names(dim(lon)) <- c('x', 'y') attr(lon, 'variables') <- metadata lat <- t(array(seq(-90, 90, length.out = num_lats), - dim = c(num_lats, num_lons))) + dim = c(num_lats, num_lons))) metadata <- list(lat = list(units = 'degrees_north')) names(dim(lat)) <- c('x', 'y') attr(lat, 'variables') <- metadata @@ -130,15 +189,15 @@ tas2 <- CDORemap(tas, lon, lat, 'r100x50', 'bil') num_lats <- 25 num_lons <- 50 tas <- array(1:(10*num_lats*10*num_lons*10), - dim = c(10, num_lats, 10, num_lons)) + dim = c(10, num_lats, 10, num_lons)) names(dim(tas)) <- c('a', 'j', 'b', 'i') lon <- array(seq(0, 360 - 360/num_lons, length.out = num_lons), - dim = c(num_lons, num_lats)) + dim = c(num_lons, num_lats)) metadata <- list(lon = list(units = 'degrees_east')) names(dim(lon)) <- c('i', 'j') attr(lon, 'variables') <- metadata lat <- t(array(seq(-90, 90, length.out = num_lats), - dim = c(num_lats, num_lons))) + dim = c(num_lats, num_lons))) metadata <- list(lat = list(units = 'degrees_north')) names(dim(lat)) <- c('i', 'j') attr(lat, 'variables') <- metadata @@ -148,23 +207,23 @@ tas2 <- CDORemap(tas, lon, lat, 't17grid', 'bil') num_lats <- 25 num_lons <- 50 tas <- array(1:(10*num_lats*10*num_lons), - dim = c(10, num_lats, 10, num_lons)) + dim = c(10, num_lats, 10, num_lons)) names(dim(tas)) <- c('a', 'j', 'b', 'i') lon <- array(seq(0, 360 - 360/num_lons, length.out = num_lons), - dim = c(num_lons, num_lats)) + dim = c(num_lons, num_lats)) names(dim(lon)) <- c('i', 'j') lat <- t(array(seq(-90, 90, length.out = num_lats), - dim = c(num_lats, num_lons))) + dim = c(num_lats, num_lons))) names(dim(lat)) <- c('i', 'j') tas2 <- CDORemap(tas, lon, lat, 't17grid', 'bil') tas2 <- CDORemap(tas, lon, lat, 't17grid', 'bil', FALSE) # It is ossible to specify an external NetCDF file as target grid reference tas2 <- CDORemap(tas, lon, lat, 'external_file.nc', 'bil') - } } -\note{This function was tested with CDO v.1.6.3.} +} \author{ History:\cr -0.0 - 2017-01 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Original code. + 0.0 - 2017-01 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Original code. } \keyword{datagen} + diff --git a/man/Clim.Rd b/man/Clim.Rd index fba9d492d79879d715fcd8981e00259af2356e94..3b11fe25276104183b94c85f00ca06009728dc63 100644 --- a/man/Clim.Rd +++ b/man/Clim.Rd @@ -1,67 +1,64 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Clim.R \name{Clim} \alias{Clim} \title{Computes Bias Corrected Climatologies} -\description{ -This function computes only per-pair climatologies from the experimental and observational matrices output from \code{Load()}. -To compute plain climatologies from only experimental or observational data from \code{Load()}, the following code can be used:\cr - \code{ -clim <- array(apply(obs_data, c(1, 4, 5, 6), mean), - dim = dim(obs_datta)[-c(2, 3)]) - } -The function \code{Clim()} computes per-pair climatologies using one of the following methods: - \itemize{ - \item{ -1) per-pair method (Garcia-Serrano and Doblas-Reyes, CD, 2012) - } - \item{ -2) Kharin method (Karin et al, GRL, 2012) - } - \item{ -3) Fuckar method (Fuckar et al, GRL, 2014) - } - } -\code{Clim()} computes climatologies using the startdates covered by the whole experiments/observational data sets. The startdates not available for all the data (model and obs) are excluded when computing the climatologies. -} \usage{ Clim(var_exp, var_obs, memb = TRUE, kharin = FALSE, NDV = FALSE) } \arguments{ - \item{var_exp}{ -Model data:\cr - c(nmod/nexp, nmemb/nparam, nsdates, nltime) up to\cr - c(nmod/nexp, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon) - } - \item{var_obs}{ -Observational data: \cr - c(nobs, nmemb, nsdates, nltime) up to\cr - c(nobs, nmemb, nsdates, nltime, nlevel, nlat, nlon) - } - \item{memb}{ -memb: TRUE/FALSE (1 climatology for each member). Default = TRUE. - } - \item{kharin}{ -TRUE/FALSE (if Kharin method is applied or not). Default = FALSE. - } - \item{NDV}{ -TRUE/FALSE (if Fuckar method is applied or not). Default = FALSE. - } +\item{var_exp}{Model data: c(nmod/nexp, nmemb/nparam, nsdates, nltime) up to +c(nmod/nexp, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon).} + +\item{var_obs}{Observational data: c(nobs, nmemb, nsdates, nltime) up to +c(nobs, nmemb, nsdates, nltime, nlevel, nlat, nlon).} + +\item{memb}{TRUE/FALSE (1 climatology for each member). Default = TRUE.} + +\item{kharin}{TRUE/FALSE (if Kharin method is applied or not). +Default = FALSE.} + +\item{NDV}{TRUE/FALSE (if Fuckar method is applied or not). Default = FALSE.} } \value{ - \item{clim_exp}{Array with same dimensions as var_exp except the third (starting dates) and, depending on the parameters, the second (members), which disappear.} - \item{clim_obs}{Array with same dimensions as var_obs except the third (starting dates) and, depending on the parameters, the second (members), which disappear.} +\item{clim_exp}{Array with same dimensions as var_exp except the third + (starting dates) and, depending on the parameters, the second (members), + which disappear.} +\item{clim_obs}{Array with same dimensions as var_obs except the third + (starting dates) and, depending on the parameters, the second (members), + which disappear.} +} +\description{ +This function computes only per-pair climatologies from the experimental +and observational matrices output from \code{Load()}. +To compute plain climatologies from only experimental or observational +data from \code{Load()}, the following code can be used:\cr +\code{clim <- array(apply(obs_data, c(1, 4, 5, 6), mean),}\cr +\code{ dim = dim(obs_datta)[-c(2, 3)])}\cr +The function \code{Clim()} computes per-pair climatologies using one of the +following methods: +\enumerate{ + \item{per-pair method (Garcia-Serrano and Doblas-Reyes, CD, 2012)} + \item{Kharin method (Karin et al, GRL, 2012)} + \item{Fuckar method (Fuckar et al, GRL, 2014)} +} +\code{Clim()} computes climatologies using the startdates covered by the +whole experiments/observational data sets. The startdates not available for +all the data (model and obs) are excluded when computing the climatologies. } \examples{ # Load sample data as in Load() example: example(Load) clim <- Clim(sampleData$mod, sampleData$obs) PlotClim(clim$clim_exp, clim$clim_obs, - toptitle = paste('sea surface temperature climatologies'), - ytitle = 'K', monini = 11, listexp = c('CMIP5 IC3'), - listobs = c('ERSST'), biglab = FALSE, fileout = 'tos_clim.eps') + toptitle = paste('sea surface temperature climatologies'), + ytitle = 'K', monini = 11, listexp = c('CMIP5 IC3'), + listobs = c('ERSST'), biglab = FALSE, fileout = 'tos_clim.eps') } \author{ History:\cr -0.9 - 2011-03 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to R CRAN + 0.9 - 2011-03 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr + 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to R CRAN } \keyword{datagen} + diff --git a/man/Cluster.Rd b/man/Cluster.Rd index 164477312a677c2bc20d9117da3cff557d4e0aea..70f22347fd90a91dd1477329c56520b3a4759ab7 100644 --- a/man/Cluster.Rd +++ b/man/Cluster.Rd @@ -1,82 +1,83 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Cluster.R \name{Cluster} \alias{Cluster} -\title{ -K-means Clustering. -} -\description{ -This function computes cluster centers and their time series of occurrences, -with the K-means clustering method using Euclidean distance, of an array of -input data with any number of dimensions, one of them (the 'posdates'th) -corresponding to time. By default the first dimension is expected to correspond -to time. -Specifically, it partitions the array along time axis in K groups or clusters -in which each space vector/array belongs to (i.e., is a member of) the cluster -with the nearest center or centroid. This function relies on the NbClust -package (Charrad et al., 2014 JSS). -} +\title{K-means Clustering} \usage{ -Cluster(var, weights, nclusters = NULL, index = 'sdindex', posdates = 1) +Cluster(var, weights, nclusters = NULL, index = "sdindex", posdates = 1) } \arguments{ - \item{var}{ -An array with any number of dimensions, one of them (the 'posdates'th) -corresponding to time with either area-averages over a series of domains or -the grid points for any sptial grid structure (x), (y), (z), (x,y), (x,y,z), -(y,z), ... - } - \item{weights}{ -A vector/array of multiplicative weights based on the areas covering each -domain/region or grid-cell of var; the dimensions of weights vector must be -equal to the dimensions of 'var' without the 'posdates'th dimension. - } - \item{nclusters}{ -This is positive integer K that must be bigger than 1. K is the number of clusters -to be computed, or K initial cluster centers to be used in the method. Default is NULL -and then user has to specify which index from NbClust and the associated criteria for -selecting the optimal number of clusters will be used for K-means clustering of var. - } - \item{index}{ -A validity index from NbClust package that can be used to determine optimal K -if K is not specified as positive integer bigger than 1 or initial/seed cluster -centers in nclusters. 'sdindex' is deafult (Halkidi et al. 2001, JIIS). Other -indices also available in NBClust are "kl", "ch", "hartigan", "ccc", "scott", "marriot", -"trcovw", "tracew", "friedman", "rubin", "cindex", "db", "silhouette", "duda", "pseudot2", -"beale", "ratkowsky", "ball", "ptbiserial", "gap", "frey", "mcclain", "gamma", "gplus", -"tau", "dunn", "hubert", "sdindex", and "sdbw". One can also use all of them with -the option 'alllong' or almost all indices except gap, gamma, gplus and tau with 'all', -when the optimal number of clusters K is detremined by the majority rule (the maximum of -histogram of the results of all indices with finite solutions). Use of some indices on -a big and/or unstructured dataset can be computationally intense and/or could lead to -numerical singularity. - } - \item{posdates}{ -The index of the dimension that corresponds to time in the provided array in the parameter -'var', the first by default. - } +\item{var}{An array with any number of dimensions, one of them (the +'posdates'th) corresponding to time with either area-averages over a +series of domains or the grid points for any sptial grid structure (x), +(y), (z), (x,y), (x,y,z), (y,z), ...} + +\item{weights}{A vector/array of multiplicative weights based on the areas +covering each domain/region or grid-cell of var; the dimensions of weights +vector must be equal to the dimensions of 'var' without the +'posdates'th dimension.} + +\item{nclusters}{This is positive integer K that must be bigger than 1. +K is the number of clusters to be computed, or K initial cluster centers +to be used in the method. Default is NULL and then user has to specify +which index from NbClust and the associated criteria for selecting the +optimal number of clusters will be used for K-means clustering of var.} + +\item{index}{A validity index from NbClust package that can be used to +determine optimal K if K is not specified as positive integer bigger than +1 or initial/seed cluster centers in nclusters. 'sdindex' is deafult +(Halkidi et al. 2001, JIIS). Other indices also available in NBClust are +"kl", "ch", "hartigan", "ccc", "scott", "marriot", "trcovw", "tracew", +"friedman", "rubin", "cindex", "db", "silhouette", "duda", "pseudot2", +"beale", "ratkowsky", "ball", "ptbiserial", "gap", "frey", "mcclain", +"gamma", "gplus", "tau", "dunn", "hubert", "sdindex", and "sdbw". +One can also use all of them with the option 'alllong' or almost all indices +except gap, gamma, gplus and tau with 'all', when the optimal number of +clusters K is detremined by the majority rule (the maximum of histogram of +the results of all indices with finite solutions). Use of some indices on +a big and/or unstructured dataset can be computationally intense and/or +could lead to numerical singularity.} + +\item{posdates}{The index of the dimension that corresponds to time in the +provided array in the parameter 'var', the first by default.} } \value{ - \item{cluster}{ -A vector (time series) of integers indicating the occurrence of a cluster, i.e., when -certain data member in time is allocated to a specific cluster (e.g., 2 1 3 1 1 1 ..). - } - \item{centers}{ -A matrix of cluster centres or centroids (e.g. [1:K, 1:spatial degrees of freedom]). - } - \item{totss}{ -The total sum of squares. - } - \item{withinss}{ -A vector of within-cluster sum of squares, one component per cluster. - } - \item{tot.withinss}{ -Total within-cluster sum of squares, i.e., sum(withinss). - } - \item{betweenss}{ -The between-cluster sum of squares, i.e. totss-tot.withinss. - } - \item{size}{ -The number of points in each cluster. - } +\item{cluster}{ + A vector (time series) of integers indicating the occurrence + of a cluster, i.e., when 'certain data member in time is allocated to a + specific cluster (e.g., 2 1 3 1 1 1 ..). +} +\item{centers}{ + A matrix of cluster centres or centroids (e.g. + [1:K, 1:spatial degrees of freedom]). +} +\item{totss}{ + The total sum of squares. +} +\item{withinss}{ + A vector of within-cluster sum of squares, one component + per cluster. +} +\item{tot.withinss}{ + Total within-cluster sum of squares, + i.e., sum(withinss). +} +\item{betweenss}{ + The between-cluster sum of squares, i.e. totss-tot.withinss. +} +\item{size}{ +The number of points in each cluster. +} +} +\description{ +This function computes cluster centers and their time series of occurrences, +with the K-means clustering method using Euclidean distance, of an array of +input data with any number of dimensions, one of them (the 'posdates'th) +corresponding to time. By default the first dimension is expected to +correspond to time. Specifically, it partitions the array along time axis in +K groups or clusters in which each space vector/array belongs to (i.e., is a +member of) the cluster with the nearest center or centroid. This function +relies on the NbClust package (Charrad et al., 2014 JSS). } \examples{ # Generating synthetic data @@ -88,20 +89,20 @@ c0 <- seq(1, 200) c1 <- sort(sample(x = 1:200, size = sample(x = 50:150, size = 1), replace = FALSE)) x1 <- c(1, 1, 1, 1) for (i1 in c1) { - a1[i1, ] <- x1 + rnorm(4, mean = mean1, sd = sd1) + a1[i1, ] <- x1 + rnorm(4, mean = mean1, sd = sd1) } -c1p5 <- c0[!(c0 \%in\% c1)] +c1p5 <- c0[!(c0 \\\%in\\\% c1)] c2 <- c1p5[seq(1, length(c1p5), 2)] x2 <- c(2, 2, 4, 4) for (i2 in c2) { - a1[i2, ] <- x2 + rnorm(4, mean = mean1, sd = sd1) + a1[i2, ] <- x2 + rnorm(4, mean = mean1, sd = sd1) } c3 <- c1p5[seq(2, length(c1p5), 2)] x3 <- c(3, 3, 1, 1) for (i3 in c3) { - a1[i3, ] <- x3 + rnorm(4, mean = mean1, sd = sd1) + a1[i3, ] <- x3 + rnorm(4, mean = mean1, sd = sd1) } # Computing the clusters @@ -113,11 +114,12 @@ res2 <- Cluster(var = a1, weights = array(1, dim = dim(a1)[2])) print(res2$cluster) print(res2$centers) } -\references{ -Wilks, 2011, Statistical Methods in the Atmospheric Sciences, 3rd ed., Elsevire, pp 676. -} \author{ -History: -1.0 # 2014-10 (N.S. Fuckar, neven.fuckar@bsc.es) # Original code +History:\cr + 1.0 # 2014-10 (N.S. Fuckar, \email{neven.fuckar@bsc.es}) - Original code +} +\references{ +Wilks, 2011, Statistical Methods in the Atmospheric Sciences, 3rd ed., Elsevire, pp 676. } \keyword{datagen} + diff --git a/man/ColorBar.Rd b/man/ColorBar.Rd index 51ca567029edd49ca38e0f0daac7816acee1ba29..205c25e4ab46159414c51819b68796eb1437b22e 100644 --- a/man/ColorBar.Rd +++ b/man/ColorBar.Rd @@ -1,126 +1,188 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ColorBar.R \name{ColorBar} \alias{ColorBar} \title{Draws a Color Bar} -\description{ -Generates a color bar to use as colouring function for map plots and optionally draws it (horizontally or vertically) to be added to map multipanels or plots. It is possible to draw triangles at the ends of the colour bar to represent values that go beyond the range of interest. A number of options is provided to adjust the colours and the position and size of the components. The drawn colour bar spans a whole figure region and is compatible with figure layouts.\cr\cr -The generated colour bar consists of a set of breaks that define the length(brks) - 1 intervals to classify each of the values in each of the grid cells of a two-dimensional field. The corresponding grid cell of a given value of the field will be coloured in function of the interval it belongs to.\cr\cr -The only mandatory parameters are 'var_limits' or 'brks' (in its second format, see below). -} \usage{ -ColorBar(brks = NULL, cols = NULL, vertical = TRUE, - subsampleg = NULL, bar_limits = NULL, var_limits = NULL, - triangle_ends = NULL, col_inf = NULL, col_sup = NULL, - color_fun = clim.palette(), plot = TRUE, draw_ticks = TRUE, - draw_separators = FALSE, triangle_ends_scale = 1, - extra_labels = NULL, title = NULL, title_scale = 1, - label_scale = 1, tick_scale = 1, - extra_margin = rep(0, 4), label_digits = 4, ...) +ColorBar(brks = NULL, cols = NULL, vertical = TRUE, subsampleg = NULL, + bar_limits = NULL, var_limits = NULL, triangle_ends = NULL, + col_inf = NULL, col_sup = NULL, color_fun = clim.palette(), + plot = TRUE, draw_ticks = TRUE, draw_separators = FALSE, + triangle_ends_scale = 1, extra_labels = NULL, title = NULL, + title_scale = 1, label_scale = 1, tick_scale = 1, + extra_margin = rep(0, 4), label_digits = 4, ...) } \arguments{ - \item{brks}{ -'brks' can be provided in two formats:\cr -a) A single value with the number of breaks to be generated automatically, between the minimum and maximum specified in 'var_limits' (both inclusive). Hence the parameter 'var_limits' is mandatory if 'brks' is provided with this format. If 'bar_limits' is additionally provided, values only between 'bar_limits' will be generated. The higher the value of 'brks', the smoother the plot will look.\cr -b) A vector with the actual values of the desired breaks. Values will be reordered by force to ascending order. If provided in this format, no other parameters are required to generate/plot the colour bar.\cr\cr - -This parameter is optional if 'var_limits' is specified. If 'brks' not specified but 'cols' is specified, it will take as value length(cols) + 1. If 'cols' is not specified either, 'brks' will take 21 as value.\cr\cr - } - \item{cols}{ -Vector of length(brks) - 1 valid colour identifiers, for each interval defined by the breaks. This parameter is optional and will be filled in with a vector of length(brks) - 1 colours generated with the function provided in 'color_fun' (\code{clim.colors} by default).\cr -'cols' can have one additional colour at the beginning and/or at the end with the aim to colour field values beyond the range of interest represented in the colour bar. If any of these extra colours is provided, parameter 'triangle_ends' becomes mandatory in order to disambiguate which of the ends the colours have been provided for.\cr - } - \item{vertical}{ -TRUE/FALSE for vertical/horizontal colour bar (disregarded if plot = FALSE). - } - \item{subsampleg}{ -The first of each subsampleg breaks will be ticked on the colorbar.\cr -Takes by default an approximation of a value that yields a readable tick arrangement (extreme breaks always ticked). If set to 0 or lower, no labels are drawn. See the code of the function for details or use 'extra_labels' for customized tick arrangements. - } - \item{bar_limits}{ -Vector of two numeric values with the extremes of the range of values represented in the colour bar. If 'var_limits' go beyond this interval, the drawing of triangle extremes is triggered at the corresponding sides, painted in 'col_inf' and 'col_sup'. Either of them can be set as NA and will then take as value the corresponding extreme in 'var_limits' (hence a triangle end won't be triggered for these sides). Takes as default the extremes of 'brks' if available, else the same values as 'var_limits'. - } - \item{var_limits}{ -Vector of two numeric values with the minimum and maximum values of the field to represent. These are used to know whether to draw triangle ends at the extremes of the colour bar and what colour to fill them in with. If not specified, take the same value as the extremes of 'brks'. Hence the parameter 'brks' is mandatory if 'var_limits' is not specified. - } - \item{triangle_ends}{ -Vector of two logical elements, indicating whether to force the drawing of triangle ends at each of the extremes of the colour bar. This choice is automatically made from the provided 'brks', 'bar_limits', 'var_limits', 'col_inf' and 'col_sup', but the behaviour can be manually forced to draw or not to draw the triangle ends with this parameter. If 'cols' is provided, 'col_inf' and 'col_sup' will take priority over 'triangle_ends' when deciding whether to draw the triangle ends or not. - } - \item{col_inf}{ -Colour to fill the inferior triangle end with. Useful if specifying colours manually with parameter 'cols', to specify the colour and to trigger the drawing of the lower extreme triangle, or if 'cols' is not specified, to replace the colour automatically generated by ColorBar(). - } - \item{col_sup}{ -Colour to fill the superior triangle end with. Useful if specifying colours manually with parameter 'cols', to specify the colour and to trigger the drawing of the upper extreme triangle, or if 'cols' is not specified, to replace the colour automatically generated by ColorBar(). - } - \item{color_fun}{ -Function to generate the colours of the color bar. Must take an integer and must return as many colours. The returned colour vector can have the attribute 'na_color', with a colour to draw NA values. This parameter is set by default to clim.palette(). - } - \item{plot}{ -Logical value indicating whether to only compute its breaks and colours (FALSE) or to also draw it on the current device (TRUE). - } - \item{draw_ticks}{ -Whether to draw ticks for the labels along the colour bar (TRUE) or not (FALSE). TRUE by default. Disregarded if 'plot = FALSE'. - } - \item{draw_separators}{ -Whether to draw black lines in the borders of each of the colour rectancles of the colour bar (TRUE) or not (FALSE). FALSE by default. Disregarded if 'plot = FALSE'. - } - \item{triangle_ends_scale}{ -Scale factor for the drawn triangle ends of the colour bar, if drawn at all. Takes 1 by default (rectangle triangle proportional to the thickness of the colour bar). Disregarded if 'plot = FALSE'. - } - \item{extra_labels}{ -Numeric vector of extra labels to draw along axis of the colour bar. The number of provided decimals will be conserved. Disregarded if 'plot = FALSE'. - } - \item{title}{ -Title to draw on top of the colour bar, most commonly with the units of the represented field in the neighbour figures. Empty by default. - } - \item{title_scale}{ -Scale factor for the 'title' of the colour bar. Takes 1 by default. - } - \item{label_scale}{ -Scale factor for the labels of the colour bar. Takes 1 by default. - } - \item{tick_scale}{ -Scale factor for the length of the ticks of the labels along the colour bar. Takes 1 by default. - } - \item{extra_margin}{ -Extra margins to be added around the colour bar, in the format c(y1, x1, y2, x2). The units are margin lines. Takes rep(0, 4) by default. - } - \item{label_digits}{ -Number of significant digits to be displayed in the labels of the colour bar, usually to avoid too many decimal digits overflowing the figure region. This does not have effect over the labels provided in 'extra_labels'. Takes 4 by default. - } - \item{...}{ -Arguments to be passed to the method. Only accepts the following graphical parameters: - -adj ann ask bg bty cex.lab cex.main cex.sub cin col.axis col.lab col.main col.sub cra crt csi cxy err family fg fig fin font font.axis font.lab font.main font.sub lend lheight ljoin lmitre lty lwd mai mex mfcol mfrow mfg mkh oma omd omi page pch pin plt pty smo srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog - -For more information about the parameters see `par` - } +\item{brks}{Can be provided in two formats: +\itemize{ + \item{A single value with the number of breaks to be generated + automatically, between the minimum and maximum specified in 'var_limits' + (both inclusive). Hence the parameter 'var_limits' is mandatory if 'brks' + is provided with this format. If 'bar_limits' is additionally provided, + values only between 'bar_limits' will be generated. The higher the value + of 'brks', the smoother the plot will look.} + \item{A vector with the actual values of the desired breaks. Values will + be reordered by force to ascending order. If provided in this format, no + other parameters are required to generate/plot the colour bar.} +} + This parameter is optional if 'var_limits' is specified. If 'brks' not + specified but 'cols' is specified, it will take as value length(cols) + 1. + If 'cols' is not specified either, 'brks' will take 21 as value.} + +\item{cols}{Vector of length(brks) - 1 valid colour identifiers, for each +interval defined by the breaks. This parameter is optional and will be +filled in with a vector of length(brks) - 1 colours generated with the +function provided in 'color_fun' (\code{clim.colors} by default).\cr 'cols' +can have one additional colour at the beginning and/or at the end with the +aim to colour field values beyond the range of interest represented in the +colour bar. If any of these extra colours is provided, parameter +'triangle_ends' becomes mandatory in order to disambiguate which of the +ends the colours have been provided for.} + +\item{vertical}{TRUE/FALSE for vertical/horizontal colour bar +(disregarded if plot = FALSE).} + +\item{subsampleg}{The first of each subsampleg breaks will be ticked on the +colorbar. Takes by default an approximation of a value that yields a +readable tick arrangement (extreme breaks always ticked). If set to 0 or +lower, no labels are drawn. See the code of the function for details or +use 'extra_labels' for customized tick arrangements.} + +\item{bar_limits}{Vector of two numeric values with the extremes of the +range of values represented in the colour bar. If 'var_limits' go beyond +this interval, the drawing of triangle extremes is triggered at the +corresponding sides, painted in 'col_inf' and 'col_sup'. Either of them +can be set as NA and will then take as value the corresponding extreme in +'var_limits' (hence a triangle end won't be triggered for these sides). +Takes as default the extremes of 'brks' if available, else the same values +as 'var_limits'.} + +\item{var_limits}{Vector of two numeric values with the minimum and maximum +values of the field to represent. These are used to know whether to draw +triangle ends at the extremes of the colour bar and what colour to fill +them in with. If not specified, take the same value as the extremes of +'brks'. Hence the parameter 'brks' is mandatory if 'var_limits' is not +specified.} + +\item{triangle_ends}{Vector of two logical elements, indicating whether to +force the drawing of triangle ends at each of the extremes of the colour +bar. This choice is automatically made from the provided 'brks', +'bar_limits', 'var_limits', 'col_inf' and 'col_sup', but the behaviour +can be manually forced to draw or not to draw the triangle ends with this +parameter. If 'cols' is provided, 'col_inf' and 'col_sup' will take +priority over 'triangle_ends' when deciding whether to draw the triangle +ends or not.} + +\item{col_inf}{Colour to fill the inferior triangle end with. Useful if +specifying colours manually with parameter 'cols', to specify the colour +and to trigger the drawing of the lower extreme triangle, or if 'cols' is +not specified, to replace the colour automatically generated by ColorBar().} + +\item{col_sup}{Colour to fill the superior triangle end with. Useful if +specifying colours manually with parameter 'cols', to specify the colour +and to trigger the drawing of the upper extreme triangle, or if 'cols' is +not specified, to replace the colour automatically generated by ColorBar().} + +\item{color_fun}{Function to generate the colours of the color bar. Must +take an integer and must return as many colours. The returned colour vector +can have the attribute 'na_color', with a colour to draw NA values. This +parameter is set by default to clim.palette().} + +\item{plot}{Logical value indicating whether to only compute its breaks and +colours (FALSE) or to also draw it on the current device (TRUE).} + +\item{draw_ticks}{Whether to draw ticks for the labels along the colour bar +(TRUE) or not (FALSE). TRUE by default. Disregarded if 'plot = FALSE'.} + +\item{draw_separators}{Whether to draw black lines in the borders of each of +the colour rectancles of the colour bar (TRUE) or not (FALSE). FALSE by +default. Disregarded if 'plot = FALSE'.} + +\item{triangle_ends_scale}{Scale factor for the drawn triangle ends of the +colour bar, if drawn at all. Takes 1 by default (rectangle triangle +proportional to the thickness of the colour bar). Disregarded if +'plot = FALSE'.} + +\item{extra_labels}{Numeric vector of extra labels to draw along axis of +the colour bar. The number of provided decimals will be conserved. +Disregarded if 'plot = FALSE'.} + +\item{title}{Title to draw on top of the colour bar, most commonly with the +units of the represented field in the neighbour figures. Empty by default.} + +\item{title_scale}{Scale factor for the 'title' of the colour bar. +Takes 1 by default.} + +\item{label_scale}{Scale factor for the labels of the colour bar. +Takes 1 by default.} + +\item{tick_scale}{Scale factor for the length of the ticks of the labels +along the colour bar. Takes 1 by default.} + +\item{extra_margin}{Extra margins to be added around the colour bar, +in the format c(y1, x1, y2, x2). The units are margin lines. Takes +rep(0, 4) by default.} + +\item{label_digits}{Number of significant digits to be displayed in the +labels of the colour bar, usually to avoid too many decimal digits +overflowing the figure region. This does not have effect over the labels +provided in 'extra_labels'. Takes 4 by default.} + +\item{...}{Arguments to be passed to the method. Only accepts the following + graphical parameters:\cr adj ann ask bg bty cex.lab cex.main cex.sub cin + col.axis col.lab col.main col.sub cra crt csi cxy err family fg fig fin + font font.axis font.lab font.main font.sub lend lheight ljoin lmitre lty + lwd mai mex mfcol mfrow mfg mkh oma omd omi page pch pin plt pty smo srt + tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog.\cr For more +information about the parameters see `par`.} } \value{ - \item{brks}{ -Breaks used for splitting the range in intervals. - } - \item{cols}{ -Colours generated for each of the length(brks) - 1 intervals. Always of length length(brks) - 1. - } - \item{col_inf}{ -Colour used to draw the lower triangle end in the colour bar (NULL if not drawn at all). - } - \item{col_sup}{ -Colour used to draw the upper triangle end in the colour bar (NULL if not drawn at all). - } +\item{brks}{ + Breaks used for splitting the range in intervals. +} +\item{cols}{ + Colours generated for each of the length(brks) - 1 intervals. + Always of length length(brks) - 1. +} +\item{col_inf}{ + Colour used to draw the lower triangle end in the colour + bar (NULL if not drawn at all). +} +\item{col_sup}{ + Colour used to draw the upper triangle end in the colour + bar (NULL if not drawn at all). +} +} +\description{ +Generates a color bar to use as colouring function for map plots and +optionally draws it (horizontally or vertically) to be added to map +multipanels or plots. It is possible to draw triangles at the ends of the +colour bar to represent values that go beyond the range of interest. A +number of options is provided to adjust the colours and the position and +size of the components. The drawn colour bar spans a whole figure region +and is compatible with figure layouts.\cr\cr +The generated colour bar consists of a set of breaks that define the +length(brks) - 1 intervals to classify each of the values in each of the +grid cells of a two-dimensional field. The corresponding grid cell of a +given value of the field will be coloured in function of the interval it +belongs to.\cr\cr +The only mandatory parameters are 'var_limits' or 'brks' (in its second +format, see below). } \examples{ cols <- c("dodgerblue4", "dodgerblue1", "forestgreen", "yellowgreen", "white", - "white", "yellow", "orange", "red", "saddlebrown") + "white", "yellow", "orange", "red", "saddlebrown") lims <- seq(-1, 1, 0.2) ColorBar(lims, cols) } \author{ History:\cr -0.1 - 2012-04 (V. Guemas, \email{virginie.guemas at bsc.es}) - Original code\cr -0.2 - 2013-04 (I. Andreu-Burillo, \email{isabel.andreu-burillo at bsc.es}) - Vert option\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Formatting to CRAN\cr -1.1 - 2013-09 (C. Prodhomme, \email{chloe.prodhomme at bsc.es}) - Add cex option\cr -1.2 - 2016-08 (N. Manubens, \email{nicolau.manubens at bsc.es}) - New ColorBar\cr - (V. Torralba, \email{veronica.torralba at bsc.es}) + 0.1 - 2012-04 (V. Guemas, \email{virginie.guemas@bsc.es}) - Original code\cr + 0.2 - 2013-04 (I. Andreu-Burillo, \email{isabel.andreu-burillo@bsc.es}) - Vert option\cr + 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Formatting to CRAN\cr + 1.1 - 2013-09 (C. Prodhomme, \email{chloe.prodhomme@bsc.es}) - Add cex option\cr + 1.2 - 2016-08 (N. Manubens, \email{nicolau.manubens@bsc.es}) - New ColorBar\cr + (V. Torralba, \email{veronica.torralba@bsc.es}) } \keyword{dplot} + diff --git a/man/Composite.Rd b/man/Composite.Rd index e2f28792abbc45360410e5cfb1c57d8221803127..4e990020d18f83c62e7104c49cd39c3985ab62ef 100644 --- a/man/Composite.Rd +++ b/man/Composite.Rd @@ -1,50 +1,46 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Composite.R \name{Composite} \alias{Composite} -\title{ - Computes composites. -} -\description{ - Composites a 3-d field var(x,y,time) according to the indices of - mode/cluster occurrences in time and computes the pvalues (t-test). - x and y are typically lon and lat, but function can accept other 2-d - fields such as lat and depth, lon and depth, etc. -} +\title{Computes composites} \usage{ - Composite(var, occ, lag=0, eno=FALSE, fileout=NULL) +Composite(var, occ, lag = 0, eno = FALSE, fileout = NULL) } \arguments{ - \item{var}{ - 3-dimensional array (x, y, time) containing the variable to composite. - } - \item{occ}{ - 1-dimensional array for the occurrence time series of mode(s)/cluster(s) - (*1) when one wants to composite all modes, e.g., all K=3 clusters then - for example occurrences could look like: 1 1 2 3 2 3 1 3 3 2 3 2 2 3 2, - (*2) otherwise for compositing only the 2nd mode or cluster of the above - example occurrences should look like 0 0 1 0 1 0 0 0 0 1 0 1 1 0 1. - } - \item{lag}{ - Lag time step (an integer), e.g., for lag=2 composite will use +2 - occurrences (i.e., shifted 2 time steps forward). Deafult is lag=0. - } - \item{eno}{ - For using the effective sample size (TRUE) or the total sample size - (FALSE that is the default) for the number of degrees of freedom. - } - \item{fileout}{ - Name of the .sav output file (NULL is the default). - } +\item{var}{3-dimensional array (x, y, time) containing the variable to +composite.} + +\item{occ}{1-dimensional array for the occurrence time series of +mode(s)/cluster(s). +(*1) When one wants to composite all modes, e.g., all K = 3 clusters then + for example occurrences could look like: 1 1 2 3 2 3 1 3 3 2 3 2 2 3 2. +(*2) Otherwise for compositing only the 2nd mode or cluster of the above + example occurrences should look like 0 0 1 0 1 0 0 0 0 1 0 1 1 0 1.} + +\item{lag}{Lag time step (an integer), e.g., for lag = 2 composite will +use +2 occurrences (i.e., shifted 2 time steps forward). Default is lag = 0.} + +\item{eno}{For using the effective sample size (TRUE) or the total sample +size (FALSE that is the default) for the number of degrees of freedom.} + +\item{fileout}{Name of the .sav output file (NULL is the default).} } \value{ - \item{$composite}{ - 3-d array (x, y, k) containing the composites k=1,..,K for case (*1) - or only k=1 for any specific cluster, i.e., case (*2). - } - \item{$pvalue}{ - 3-d array (x, y, k) containing the pvalue of the - composites obtained through a t-test that accounts for the serial - dependence of the data with the same structure as Composite. - } +\item{$composite}{ + 3-d array (x, y, k) containing the composites k=1,..,K for case (*1) + or only k=1 for any specific cluster, i.e., case (*2). +} +\item{$pvalue}{ + 3-d array (x, y, k) containing the pvalue of the + composites obtained through a t-test that accounts for the serial + dependence of the data with the same structure as Composite. +} +} +\description{ +Composites a 3-d field var(x, y, time) according to the indices of +mode/cluster occurrences in time and computes the pvalues (t-test). x and y +are typically lon and lat, but function can accept other 2-d fields such as +lat and depth, lon and depth, etc. } \examples{ blank <- array(0, dim=c(20, 10, 30)) @@ -54,11 +50,11 @@ t1 <- blank f1 <- blank for (i in 1:20) { - x1[i,,] <- i + x1[i,,] <- i } for (i in 1:30) { - t1[,,i] <- i + t1[,,i] <- i } # This is 2D propagating sin wave example, where we use (x,y,t) structure of @@ -66,9 +62,9 @@ for (i in 1:30) { # steps can lead to modification or cancelation of wave pattern. for (i in 1:20) { - for (j in 1:30) { - f1[i,,j] <- 3*sin(2*pi*x1[i,,j]/5. - 2*pi*t1[i,,j]/6.) - } + for (j in 1:30) { + f1[i,,j] <- 3*sin(2*pi*x1[i,,j]/5. - 2*pi*t1[i,,j]/6.) + } } occ1 <- rep(0, 30) @@ -80,10 +76,10 @@ occ2 <- rep(0, 30) occ2[c(3, 9, 15, 21)] <- 1 filled.contour(Composite(var=f1, occ=occ2)$composite[,,1]) - } \author{ - History: - 0.1 # 2014-08 (N.S. Fuckar, \email{neven.fuckar@bsc.es}) # Original code +History: + 0.1 # 2014-08 (N.S. Fuckar, \email{neven.fuckar@bsc.es}) # Original code } \keyword{datagen} + diff --git a/man/ConfigApplyMatchingEntries.Rd b/man/ConfigApplyMatchingEntries.Rd index 15e504695c56f6da7efe947ff05012a7d396ca82..626e385de264d6111c3cfbef55eb3c37915aeb32 100644 --- a/man/ConfigApplyMatchingEntries.Rd +++ b/man/ConfigApplyMatchingEntries.Rd @@ -1,69 +1,77 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ConfigApplyMatchingEntries.R \name{ConfigApplyMatchingEntries} \alias{ConfigApplyMatchingEntries} -\title{ -Apply Matching Entries To Dataset Name And Variable Name To Find Related Info -} -\description{ -Given a pair of dataset name and variable name, this function determines applies all the matching entries found in the corresponding configuration table to work out the dataset main path, file path, actual name of variable inside NetCDF files, ... -} +\title{Apply Matching Entries To Dataset Name And Variable Name To Find Related Info} \usage{ -ConfigApplyMatchingEntries(configuration, var, exp = NULL, obs = NULL, - show_entries = FALSE, show_result = TRUE) +ConfigApplyMatchingEntries(configuration, var, exp = NULL, obs = NULL, + show_entries = FALSE, show_result = TRUE) } \arguments{ - \item{configuration}{ -Configuration object obtained from ConfigFileOpen() or ConfigFileCreate(). - } - \item{var}{ -Name of the variable to load. Will be interpreted as a string, regular expressions do not apply here.\cr -Examples: 'tas' or 'tasmax_q90'. - } - \item{exp}{ -Set of experimental dataset identifiers. Will be interpreted as a strings, regular expressions do not apply here.\cr -Can be NULL (not to check in experimental dataset tables), and takes by default NULL.\cr -Examples: c('EnsEcmwfSeas', 'EnsUkmoSeas'), c('i00k'). - } - \item{obs}{ -Set of observational dataset identifiers. Will be interpreted as a strings, regular expressions do not apply here.\cr -Can be NULL (not to check in observational dataset tables), and takes by default NULL.\cr -Examples: c('GLORYS', 'ERAint'), c('NCEP'). - } - \item{show_entries}{ -Flag to stipulate whether to show the found matching entries for all datasets and variable name. - } - \item{show_result}{ -Flag to stipulate whether to show the result of applying all the matching entries (dataset main path, file path, ...). - } +\item{configuration}{Configuration object obtained from ConfigFileOpen() +or ConfigFileCreate().} + +\item{var}{Name of the variable to load. Will be interpreted as a string, +regular expressions do not apply here. +Examples: 'tas' or 'tasmax_q90'.} + +\item{exp}{Set of experimental dataset identifiers. Will be interpreted as +a strings, regular expressions do not apply here. Can be NULL (not to +check in experimental dataset tables), and takes by default NULL. +Examples: c('EnsEcmwfSeas', 'EnsUkmoSeas'), c('i00k').} + +\item{obs}{Set of observational dataset identifiers. Will be interpreted as +a strings, regular expressions do not apply here. Can be NULL (not to +check in observational dataset tables), and takes by default NULL. +Examples: c('GLORYS', 'ERAint'), c('NCEP').} + +\item{show_entries}{Flag to stipulate whether to show the found matching +entries for all datasets and variable name.} + +\item{show_result}{Flag to stipulate whether to show the result of applying +all the matching entries (dataset main path, file path, ...).} } \value{ -A list with the information resulting of applying the matching entries is returned. +A list with the information resulting of applying the matching + entries is returned. } -\seealso{ConfigApplyMatchingEntries, ConfigEditDefinition, ConfigEditEntry, ConfigFileOpen, ConfigShowSimilarEntries, ConfigShowTable} -\author{ -History:\cr -0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - First version -1.0 - 2015-11 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Removed grid column and storage types +\description{ +Given a pair of dataset name and variable name, this function determines +applies all the matching entries found in the corresponding configuration +table to work out the dataset main path, file path, actual name of variable +inside NetCDF files, ... } \examples{ # Create an empty configuration file config_file <- paste0(tempdir(), "/example.conf") -ConfigFileCreate(config_file, confirm = FALSE) +s2dverification:::ConfigFileCreate(config_file, confirm = FALSE) # Open it into a configuration object configuration <- ConfigFileOpen(config_file) # Add an entry at the bottom of 4th level of file-per-startdate experiments # table which will associate the experiment "ExampleExperiment2" and variable # "ExampleVariable" to some information about its location. configuration <- ConfigAddEntry(configuration, "experiments", - "last", "ExampleExperiment2", "ExampleVariable", - "/path/to/ExampleExperiment2/", - "ExampleVariable/ExampleVariable_$START_DATE$.nc") + "last", "ExampleExperiment2", "ExampleVariable", + "/path/to/ExampleExperiment2/", + "ExampleVariable/ExampleVariable_$START_DATE$.nc") # Edit entry to generalize for any variable. Changing variable needs . configuration <- ConfigEditEntry(configuration, "experiments", 1, - var_name = ".*", - file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") + var_name = ".*", + file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") # Now apply matching entries for variable and experiment name and show the # result match_info <- ConfigApplyMatchingEntries(configuration, 'tas', - exp = c('ExampleExperiment2'), show_result = TRUE) + exp = c('ExampleExperiment2'), show_result = TRUE) +} +\author{ +History:\cr + 0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - First version\cr + 1.0 - 2015-11 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Removed grid column and storage types +} +\seealso{ +ConfigApplyMatchingEntries, ConfigEditDefinition, + ConfigEditEntry, ConfigFileOpen, ConfigShowSimilarEntries, + ConfigShowTable } \keyword{datagen} + diff --git a/man/ConfigEditDefinition.Rd b/man/ConfigEditDefinition.Rd index 9da8c09d9b2e79bc869fc3e3dedaa3f511db30ce..b1f7c8821ab97d044bd78e22996c4d9f0984380c 100644 --- a/man/ConfigEditDefinition.Rd +++ b/man/ConfigEditDefinition.Rd @@ -1,38 +1,33 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ConfigEditDefinition.R \name{ConfigEditDefinition} \alias{ConfigEditDefinition} \alias{ConfigRemoveDefinition} -\title{ -Add Modify Or Remove Variable Definitions In Configuration -} -\description{ -These functions help in adding, modifying or removing variable definitions in a configuration object obtained wit ConfigFileOpen() or ConfigFileCreate().\cr -ConfigEditDefinition() will add the definition if not existing. -} +\title{Add Modify Or Remove Variable Definitions In Configuration} \usage{ ConfigEditDefinition(configuration, name, value, confirm = TRUE) + ConfigRemoveDefinition(configuration, name) } \arguments{ - \item{configuration}{ -Configuration object obtained wit ConfigFileOpen() or ConfigFileCreate(). - } - \item{name}{ -Name of the variable to add/modify/remove. - } - \item{value}{ -Value to associate to the variable. - } - \item{confirm}{ -Flag to stipulate whether to ask for confirmation if the variable is being modified. Takes by default TRUE. - } +\item{configuration}{Configuration object obtained wit ConfigFileOpen() or +ConfigFileCreate().} + +\item{name}{Name of the variable to add/modify/remove.} + +\item{value}{Value to associate to the variable.} + +\item{confirm}{Flag to stipulate whether to ask for confirmation if the +variable is being modified. Takes by default TRUE.} } \value{ A modified configuration object is returned. } -\seealso{ConfigApplyMatchingEntries, ConfigEditDefinition, ConfigEditEntry, ConfigFileOpen, ConfigShowSimilarEntries, ConfigShowTable} -\author{ -History:\cr -0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - First version +\description{ +These functions help in adding, modifying or removing variable definitions +in a configuration object obtained with \code{\link{ConfigFileOpen}} or +\code{\link{ConfigFileCreate}}. ConfigEditDefinition() will add the +definition if not existing. } \examples{ # Create an empty configuration file @@ -44,16 +39,27 @@ configuration <- ConfigFileOpen(config_file) # table which will associate the experiment "ExampleExperiment2" and variable # "ExampleVariable" to some information about its location. configuration <- ConfigAddEntry(configuration, "experiments", - "last", "ExampleExperiment2", "ExampleVariable", - "/path/to/ExampleExperiment2/", - "ExampleVariable/ExampleVariable_$START_DATE$.nc") + "last", "ExampleExperiment2", "ExampleVariable", + "/path/to/ExampleExperiment2/", + "ExampleVariable/ExampleVariable_$START_DATE$.nc") # Edit entry to generalize for any variable. Changing variable needs . configuration <- ConfigEditEntry(configuration, "experiments", 1, - var_name = ".*", - file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") + var_name = ".*", + file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") # Now apply matching entries for variable and experiment name and show the # result match_info <- ConfigApplyMatchingEntries(configuration, 'tas', - exp = c('ExampleExperiment2'), show_result = TRUE) + exp = c('ExampleExperiment2'), show_result = TRUE) + +} +\author{ +History: + 0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - First version +} +\seealso{ +[ConfigApplyMatchingEntries()], [ConfigEditDefinition()], + [ConfigEditEntry()], [ConfigFileOpen()], [ConfigShowSimilarEntries()], + [ConfigShowTable()]. } \keyword{datagen} + diff --git a/man/ConfigEditEntry.Rd b/man/ConfigEditEntry.Rd index d73945888a052ec00e8ebee44a5dccb7ef36e71a..83973231bcc5d40fe2264b789f0beaea3b110dd8 100644 --- a/man/ConfigEditEntry.Rd +++ b/man/ConfigEditEntry.Rd @@ -1,57 +1,69 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ConfigEditEntry.R \name{ConfigEditEntry} \alias{ConfigAddEntry} \alias{ConfigEditEntry} \alias{ConfigRemoveEntry} -\title{ -Add, Remove Or Edit Entries In The Configuration -} -\description{ -ConfigAddEntry(), ConfigEditEntry() and ConfigRemoveEntry() are functions to manage entries in a configuration object created with ConfigFileOpen().\cr -Before adding an entry, make sure the defaults don't do already what you want (ConfigShowDefinitions(), ConfigShowTable()).\cr -Before adding an entry, make sure it doesn't override and spoil what other entries do (ConfigShowTable(), ConfigFileOpen()).\cr -Before adding an entry, make sure there aren't other entries that already do what you want (ConfigShowSimilarEntries()).\cr -} +\title{Add, Remove Or Edit Entries In The Configuration} \usage{ -ConfigAddEntry(configuration, dataset_type, position = "last", - dataset_name = ".*", var_name = ".*", main_path = "*", - file_path = "*", nc_var_name = "*", suffix = "*", - varmin = "*", varmax = "*") -ConfigEditEntry(configuration, dataset_type, position, - dataset_name = NULL, var_name = NULL, main_path = NULL, - file_path = NULL, nc_var_name = NULL, - suffix = NULL, varmin = NULL, varmax = NULL) -ConfigRemoveEntry(configuration, dataset_type, - dataset_name = NULL, var_name = NULL, position = NULL) +ConfigEditEntry(configuration, dataset_type, position, dataset_name = NULL, + var_name = NULL, main_path = NULL, file_path = NULL, + nc_var_name = NULL, suffix = NULL, varmin = NULL, varmax = NULL) + +ConfigAddEntry(configuration, dataset_type, position = "last", + dataset_name = ".*", var_name = ".*", main_path = "*", + file_path = "*", nc_var_name = "*", suffix = "*", varmin = "*", + varmax = "*") + +ConfigRemoveEntry(configuration, dataset_type, dataset_name = NULL, + var_name = NULL, position = NULL) } \arguments{ - \item{configuration}{ -Configuration object obtained via ConfigFileOpen() or ConfigFileCreate() that will be modified accordingly. - } - \item{dataset_type}{ -Whether to modify a table of experimental datasets or a table of observational datasets. Can take values 'experiments' or 'observations' respectively. - } - \item{position}{ -'position' tells the index in the table of the entry to edit or remove. Use ConfigShowTable() to see the index of the entry.\cr -In ConfigAddEntry() it can also take the value "last" (default), that will put the entry at the end of the corresponding level, or "first" at the beginning. See ?ConfigFileOpen for more information.\cr -If 'dataset_name' and 'var_name' are specified this argument is ignored in ConfigRemoveEntry(). - } - \item{dataset_name,var_name,main_path,file_path,nc_var_name,suffix,varmin,varmax}{ -These parameters tell the dataset name, variable name, main path, ..., of the entry to add, edit or remove.\cr -'dataset_name' and 'var_name' can take as a value a POSIX 1003.2 regular expression (see ?ConfigFileOpen).\cr -Other parameters can take as a value a shell globbing expression (see ?ConfigFileOpen).\cr -'dataset_name' and 'var_name' take by default the regular expression '.*' (match any dataset and variable name), and the others take by default '*' (associate to the pair 'dataset_name' and 'var_name' all the defined default values. In this case '*' has a special behaviour, it won't be used as a shell globbing expression. See ?ConfigFileOpen and ?ConfigShowDefinitions).\cr +\item{configuration}{Configuration object obtained via ConfigFileOpen() +or ConfigFileCreate() that will be modified accordingly.} + +\item{dataset_type}{Whether to modify a table of experimental datasets or +a table of observational datasets. Can take values 'experiments' or +'observations' respectively.} + +\item{position}{'position' tells the index in the table of the entry to +edit or remove. Use ConfigShowTable() to see the index of the entry. +In ConfigAddEntry() it can also take the value "last" (default), that will +put the entry at the end of the corresponding level, or "first" at the +beginning. See ?ConfigFileOpen for more information. +If 'dataset_name' and 'var_name' are specified this argument is ignored in +ConfigRemoveEntry().} + +\item{dataset_name, var_name, main_path, file_path, nc_var_name, suffix, varmin, varmax}{These parameters tell the dataset name, variable name, main path, ..., of +the entry to add, edit or remove.\cr 'dataset_name' and 'var_name' can take +as a value a POSIX 1003.2 regular expression (see ?ConfigFileOpen).\cr +Other parameters can take as a value a shell globbing expression +(see ?ConfigFileOpen).\cr +'dataset_name' and 'var_name' take by default the regular expression '.*' +(match any dataset and variable name), and the others take by default '*' +(associate to the pair 'dataset_name' and 'var_name' all the defined +default values. In this case '*' has a special behaviour, it won't be +used as a shell globbing expression. See ?ConfigFileOpen and +?ConfigShowDefinitions).\cr 'var_min' and 'var_max' must be a character string.\cr -To define these values, you can use defined variables via $VARIABLE_NAME$ or other entry attributes via $ATTRIBUTE_NAME$. See ?ConfigFileOpen for more information.\cr - } +To define these values, you can use defined variables via $VARIABLE_NAME$ +or other entry attributes via $ATTRIBUTE_NAME$. See ?ConfigFileOpen for +more information.} } \value{ -The function returns an accordingly modified configuration object. To apply the changes in the configuration file it must be saved using ConfigFileSave(). +The function returns an accordingly modified configuration object. + To apply the changes in the configuration file it must be saved using + ConfigFileSave(). } -\seealso{ConfigApplyMatchingEntries, ConfigEditDefinition, ConfigEditEntry, ConfigFileOpen, ConfigShowSimilarEntries, ConfigShowTable} -\author{ -History:\cr -0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - First version -1.0 - 2015-11 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Removed grid column and storage formats +\description{ +ConfigAddEntry(), ConfigEditEntry() and ConfigRemoveEntry() are functions +to manage entries in a configuration object created with ConfigFileOpen().\cr +Before adding an entry, make sure the defaults don't do already what you +want (ConfigShowDefinitions(), ConfigShowTable()).\cr +Before adding an entry, make sure it doesn't override and spoil what other +entries do (ConfigShowTable(), ConfigFileOpen()).\cr +Before adding an entry, make sure there aren't other entries that already +do what you want (ConfigShowSimilarEntries()). } \examples{ # Create an empty configuration file @@ -63,24 +75,34 @@ configuration <- ConfigFileOpen(config_file) # table which will associate the experiment "ExampleExperiment" and variable # "ExampleVariable" to some information about its location. configuration <- ConfigAddEntry(configuration, "experiments", - "last", "ExampleExperiment", "ExampleVariable", - "/path/to/ExampleExperiment/", - "ExampleVariable/ExampleVariable_$START_DATE$.nc") + "last", "ExampleExperiment", "ExampleVariable", + "/path/to/ExampleExperiment/", + "ExampleVariable/ExampleVariable_$START_DATE$.nc") # Add another entry configuration <- ConfigAddEntry(configuration, "experiments", - "last", "ExampleExperiment2", "ExampleVariable", - "/path/to/ExampleExperiment2/", - "ExampleVariable/ExampleVariable_$START_DATE$.nc") + "last", "ExampleExperiment2", "ExampleVariable", + "/path/to/ExampleExperiment2/", + "ExampleVariable/ExampleVariable_$START_DATE$.nc") # Edit second entry to generalize for any variable. Changing variable needs . configuration <- ConfigEditEntry(configuration, "experiments", 2, - var_name = ".*", - file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") + var_name = ".*", + file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") # Remove first entry configuration <- ConfigRemoveEntry(configuration, "experiments", - "ExampleExperiment", "ExampleVariable") + "ExampleExperiment", "ExampleVariable") # Show results ConfigShowTable(configuration, "experiments") # Save the configuration ConfigFileSave(configuration, config_file, confirm = FALSE) } +\author{ +History:\cr + 0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - First version\cr + 1.0 - 2015-11 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Removed grid column and storage formats +} +\seealso{ +ConfigApplyMatchingEntries, ConfigEditDefinition, ConfigEditEntry, + ConfigFileOpen, ConfigShowSimilarEntries, ConfigShowTable +} \keyword{datagen} + diff --git a/man/ConfigFileOpen.Rd b/man/ConfigFileOpen.Rd index c42153fbf36c2b3ff11c6cee8130ad9c47d903d7..cff7427e181a886f1ba2822c9aa9923059e5b26a 100644 --- a/man/ConfigFileOpen.Rd +++ b/man/ConfigFileOpen.Rd @@ -1,151 +1,165 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ConfigFileOpen.R \name{ConfigFileOpen} -\alias{ConfigFileOpen} \alias{ConfigFileCreate} +\alias{ConfigFileOpen} \alias{ConfigFileSave} -\title{ -Functions To Create Open And Save Configuration File -} -\description{ -These functions help in creating, opening and saving configuration files. -} +\title{Functions To Create Open And Save Configuration File} \usage{ ConfigFileOpen(file_path, silent = FALSE, stop = FALSE) + ConfigFileCreate(file_path, confirm = TRUE) + ConfigFileSave(configuration, file_path, confirm = TRUE) } \arguments{ - \item{file_path}{ -Path to the configuration file to create/open/save. - } - \item{silent}{ -Flag to activate or deactivate verbose mode.\cr -Defaults to FALSE (verbose mode on). - } - \item{configuration}{ -Configuration object to save in a file. - } - \item{confirm}{ -Flag to stipulate whether to ask for confirmation when saving a configuration file that already exists.\cr -Defaults to TRUE (confirmation asked). - } - \item{stop}{ -TRUE/FALSE whether to raise an error if not all the mandatory default variables are defined in the configuration file.\cr - } +\item{file_path}{Path to the configuration file to create/open/save.} + +\item{silent}{Flag to activate or deactivate verbose mode. +Defaults to FALSE (verbose mode on).} + +\item{stop}{TRUE/FALSE whether to raise an error if not all the mandatory +default variables are defined in the configuration file.} + +\item{confirm}{Flag to stipulate whether to ask for confirmation when +saving a configuration file that already exists.\cr +Defaults to TRUE (confirmation asked).} + +\item{configuration}{Configuration object to save in a file.} +} +\value{ +ConfigFileOpen() returns a configuration object with all the information for + the configuration file mechanism to work.\cr +ConfigFileSave() returns TRUE if the file has been saved and FALSE otherwise.\cr +ConfigFileCreate() returns nothing. +} +\description{ +These functions help in creating, opening and saving configuration files. } \details{ -ConfigFileOpen() loads all the data contained in the configuration file specified as parameter 'file_path'.\cr -Returns a configuration object with the variables needed for the configuration file mechanism to work.\cr -This function is called from inside the Load() function to load the configuration file specified in 'configfile'.\cr -\cr -ConfigFileCreate() creates an empty configuration file and saves it to the specified path. It may be opened later with ConfigFileOpen() to be edited. Some default values are set when creating a file with this function, you can check these with ConfigShowDefinitions().\cr -\cr -ConfigFileSave() saves a configuration object into a file, which may then be used from Load().\cr -\cr -Two examples of configuration files can be found inside the 'inst/config/' folder in the package: - \itemize{ - \item{BSC.conf: configuration file used at BSC-CNS. Contains location data on several datasets and variables.} - \item{template.conf: very simple configuration file intended to be used as pattern when starting from scratch.} - } +ConfigFileOpen() loads all the data contained in the configuration file +specified as parameter 'file_path'. +Returns a configuration object with the variables needed for the +configuration file mechanism to work. +This function is called from inside the Load() function to load the +configuration file specified in 'configfile'.\cr\cr +ConfigFileCreate() creates an empty configuration file and saves it to +the specified path. It may be opened later with ConfigFileOpen() to be edited. +Some default values are set when creating a file with this function, you +can check these with ConfigShowDefinitions().\cr\cr +ConfigFileSave() saves a configuration object into a file, which may then +be used from Load().\cr\cr +Two examples of configuration files can be found inside the 'inst/config/' +folder in the package: + \itemize{ + \item{BSC.conf: configuration file used at BSC-CNS. Contains location + data on several datasets and variables.} + \item{template.conf: very simple configuration file intended to be used as + pattern when starting from scratch.} + } How the configuration file works:\cr -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - +~~~~~~~~~~~~~~~~~~~~~~~~~~~~\cr It contains one list and two tables.\cr -Each of these have a header that starts with '!!'. These are key lines and should not be removed or reordered.\cr +Each of these have a header that starts with '!!'. These are key lines and +should not be removed or reordered.\cr Lines starting with '#' and blank lines will be ignored. - The list should contains variable definitions and default value definitions.\cr - The first table contains information about experiments.\cr The third table contains information about observations.\cr - Each table entry is a list of comma-separated elements.\cr -The two first are part of a key that is associated to a value formed by the other elements.\cr +The two first are part of a key that is associated to a value formed by the +other elements.\cr The key elements are a dataset identifier and a variable name.\cr -The value elements are the dataset main path, dataset file path, the variable name inside the .nc file, a default suffix (explained below) and a minimum and maximum vaues beyond which loaded data is deactivated. - -Given a dataset name and a variable name, a full path is obtained concatenating the main path and the file path.\cr -Also the nc variable name, the suffixes and the limit values are obtained. - -Any of the elements in the keys can contain regular expressions[1] that will cause matching for sets of dataset names or variable names. - -The dataset path and file path can contain shell globbing expressions[2] that will cause matching for sets of paths when fetching the file in the full path.\cr -The full path can point to an OPeNDAP URL. - -Any of the elements in the value can contain variables that will be replaced to an associated string.\cr +The value elements are the dataset main path, dataset file path, the +variable name inside the .nc file, a default suffix (explained below) and a +minimum and maximum vaues beyond which loaded data is deactivated.\cr +Given a dataset name and a variable name, a full path is obtained +concatenating the main path and the file path.\cr +Also the nc variable name, the suffixes and the limit values are obtained.\cr +Any of the elements in the keys can contain regular expressions[1] that will +cause matching for sets of dataset names or variable names.\cr +The dataset path and file path can contain shell globbing expressions[2] +that will cause matching for sets of paths when fetching the file in the +full path.\cr +The full path can point to an OPeNDAP URL.\cr +Any of the elements in the value can contain variables that will be replaced +to an associated string.\cr Variables can be defined only in the list at the top of the file. \cr The pattern of a variable definition is\cr - VARIABLE_NAME = VARIABLE_VALUE\cr -and can be accessed from within the table values or from within the variable values as\cr - $VARIABLE_NAME$\cr +VARIABLE_NAME = VARIABLE_VALUE\cr +and can be accessed from within the table values or from within the variable +values as\cr + $VARIABLE_NAME$\cr For example:\cr - FILE_NAME = tos.nc\cr - !!table of experiments\cr - ecmwf, tos, /path/to/dataset/, $FILE_NAME$\cr -There are some reserved variables that will offer information about the store frequency, the current startdate Load() is fetching, etc:\cr - $VAR_NAME$, $START_DATE$, $STORE_FREQ$, $MEMBER_NUMBER$\cr - for experiments only: $EXP_NAME$\cr - for observations only: $OBS_NAME$, $YEAR$, $MONTH$, $DAY$\cr -Additionally, from an element in an entry value you can access the other elements of the entry as:\cr - $EXP_MAIN_PATH$, $EXP_FILE_PATH$, \cr$VAR_NAME$, $SUFFIX$, $VAR_MIN$, $VAR_MAX$\cr - -The variable $SUFFIX$ is useful because it can be used to take part in the main or file path. For example: '/path/to$SUFFIX$/dataset/'.\cr -It will be replaced by the value in the column that corresponds to the suffix unless the user specifies a different suffix via the parameter 'suffixexp' or 'suffixobs'.\cr -This way the user is able to load two variables with the same name in the same dataset but with slight modifications, with a suffix anywhere in the path to the data that advices of this slight modification. - + FILE_NAME = tos.nc\cr + !!table of experiments\cr + ecmwf, tos, /path/to/dataset/, $FILE_NAME$\cr +There are some reserved variables that will offer information about the +store frequency, the current startdate Load() is fetching, etc:\cr + $VAR_NAME$, $START_DATE$, $STORE_FREQ$, $MEMBER_NUMBER$\cr + for experiments only: $EXP_NAME$\cr + for observations only: $OBS_NAME$, $YEAR$, $MONTH$, $DAY$\cr +Additionally, from an element in an entry value you can access the other +elements of the entry as:\cr + $EXP_MAIN_PATH$, $EXP_FILE_PATH$, \cr$VAR_NAME$, $SUFFIX$, $VAR_MIN$, $VAR_MAX$\cr +\cr +The variable $SUFFIX$ is useful because it can be used to take part in the +main or file path. For example: '/path/to$SUFFIX$/dataset/'.\cr +It will be replaced by the value in the column that corresponds to the +suffix unless the user specifies a different suffix via the parameter +'suffixexp' or 'suffixobs'.\cr +This way the user is able to load two variables with the same name in the +same dataset but with slight modifications, with a suffix anywhere in the +path to the data that advices of this slight modification.\cr\cr The entries in a table will be grouped in 4 levels of specificity: - \enumerate{ - \item{ + \enumerate{ + \item{ General entries:\cr - - the key dataset name and variable name are both a regular expression matching any sequence of characters (.*) that will cause matching for any pair of dataset and variable names\cr - Example: .*, .*, /dataset/main/path/, file/path, nc_var_name, suffix, var_min, var_max - } - \item{ +- the key dataset name and variable name are both a regular expression +matching any sequence of characters (.*) that will cause matching for any +pair of dataset and variable names\cr + Example: .*, .*, /dataset/main/path/, file/path, nc_var_name, suffix, +var_min, var_max + } + \item{ Dataset entries:\cr - - the key variable name matches any sequence of characters\cr - Example: ecmwf, .*, /dataset/main/path/, file/path, nc_var_name, suffix, var_min, var_max - } - \item{ +- the key variable name matches any sequence of characters\cr + Example: ecmwf, .*, /dataset/main/path/, file/path, nc_var_name, + suffix, var_min, var_max + } + \item{ Variable entries:\cr - - the key dataset name matches any sequence of characters\cr - Example: .*, tos, /dataset/main/path/, file/path, nc_var_name, suffix, var_min, var_max - } - \item{ -Specific entries:\cr - - both key values are specified\cr - Example: ecmwf, tos, /dataset/main/path/, file/path, nc_var_name, suffix, var_min, var_max - } - } - -Given a pair of dataset name and variable name for which we want to know the full path, all the rules that match will be applied from more general to more specific.\cr -If there is more than one entry per group that match a given key pair, these will be applied in the order of appearance in the configuration file (top to bottom). - -An asterisk (*) in any value element will be interpreted as 'leave it as is or take the default value if yet not defined'.\cr +- the key dataset name matches any sequence of characters\cr + Example: .*, tos, /dataset/main/path/, file/path, nc_var_name, + suffix, var_min, var_max + } + \item{ + Specific entries:\cr +- both key values are specified\cr + Example: ecmwf, tos, /dataset/main/path/, file/path, nc_var_name, + suffix, var_min, var_max + } + } +Given a pair of dataset name and variable name for which we want to know the +full path, all the rules that match will be applied from more general to +more specific.\cr +If there is more than one entry per group that match a given key pair, +these will be applied in the order of appearance in the configuration file +(top to bottom).\cr\cr +An asterisk (*) in any value element will be interpreted as 'leave it as is +or take the default value if yet not defined'.\cr The default values are defined in the following reserved variables:\cr - $DEFAULT_EXP_MAIN_PATH$, $DEFAULT_EXP_FILE_PATH$, $DEFAULT_NC_VAR_NAME$, $DEFAULT_OBS_MAIN_PATH$, $DEFAULT_OBS_FILE_PATH$, $DEFAULT_SUFFIX$, $DEFAULT_VAR_MIN$, $DEFAULT_VAR_MAX$, \cr + $DEFAULT_EXP_MAIN_PATH$, $DEFAULT_EXP_FILE_PATH$, $DEFAULT_NC_VAR_NAME$, +$DEFAULT_OBS_MAIN_PATH$, $DEFAULT_OBS_FILE_PATH$, $DEFAULT_SUFFIX$, +$DEFAULT_VAR_MIN$, $DEFAULT_VAR_MAX$, \cr $DEFAULT_DIM_NAME_LATITUDES$, $DEFAULT_DIM_NAME_LONGITUDES$, \cr -$DEFAULT_DIM_NAME_MEMBERS$\cr - +$DEFAULT_DIM_NAME_MEMBERS$\cr\cr Trailing asterisks in an entry are not mandatory. For example\cr - ecmwf, .*, /dataset/main/path/, *, *, *, *, *\cr + ecmwf, .*, /dataset/main/path/, *, *, *, *, *\cr will have the same effect as\cr - ecmwf, .*, /dataset/main/path/ - -A double quote only (") in any key or value element will be interpreted as 'fill in with the same value as the entry above'. -} -\value{ -ConfigFileOpen() returns a configuration object with all the information for the configuration file mechanism to work.\cr -ConfigFileSave() returns TRUE if the file has been saved and FALSE otherwise.\cr -ConfigFileCreate() returns nothing. -} -\seealso{ConfigApplyMatchingEntries, ConfigEditDefinition, ConfigEditEntry, ConfigFileOpen, ConfigShowSimilarEntries, ConfigShowTable} -\references{ -[1] https://stat.ethz.ch/R-manual/R-devel/library/base/html/regex.html\cr -[2] http://tldp.org/LDP/abs/html/globbingref.html -} -\author{ -History:\cr -0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - First version -1.0 - 2015-11 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Removed grid column and storage formats + ecmwf, .*, /dataset/main/path/ \cr\cr +A double quote only (") in any key or value element will be interpreted as +'fill in with the same value as the entry above'. } \examples{ # Create an empty configuration file @@ -157,18 +171,33 @@ configuration <- ConfigFileOpen(config_file) # table which will associate the experiment "ExampleExperiment2" and variable # "ExampleVariable" to some information about its location. configuration <- ConfigAddEntry(configuration, "experiments", - "last", "ExampleExperiment2", "ExampleVariable", - "/path/to/ExampleExperiment2/", - "ExampleVariable/ExampleVariable_$START_DATE$.nc") + "last", "ExampleExperiment2", "ExampleVariable", + "/path/to/ExampleExperiment2/", + "ExampleVariable/ExampleVariable_$START_DATE$.nc") # Edit entry to generalize for any variable. Changing variable needs . configuration <- ConfigEditEntry(configuration, "experiments", 1, - var_name = ".*", - file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") + var_name = ".*", + file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") # Now apply matching entries for variable and experiment name and show the # result match_info <- ConfigApplyMatchingEntries(configuration, 'tas', - exp = c('ExampleExperiment2'), show_result = TRUE) + exp = c('ExampleExperiment2'), show_result = TRUE) # Finally save the configuration file. ConfigFileSave(configuration, config_file, confirm = FALSE) + +} +\author{ +History: + 0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - First version + 1.0 - 2015-11 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Removed grid column and storage formats +} +\references{ +[1] \url{https://stat.ethz.ch/R-manual/R-devel/library/base/html/regex.html}\cr +[2] \url{http://tldp.org/LDP/abs/html/globbingref.html} +} +\seealso{ +ConfigApplyMatchingEntries, ConfigEditDefinition, + ConfigEditEntry, ConfigFileOpen, ConfigShowSimilarEntries, ConfigShowTable } \keyword{datagen} + diff --git a/man/ConfigShowSimilarEntries.Rd b/man/ConfigShowSimilarEntries.Rd index 836a1ec9bcccd8a174f118f5763d0c55f65d6981..312da7957989e611973d690171dd99083ba2d3b1 100644 --- a/man/ConfigShowSimilarEntries.Rd +++ b/man/ConfigShowSimilarEntries.Rd @@ -1,67 +1,53 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ConfigShowSimilarEntries.R \name{ConfigShowSimilarEntries} \alias{ConfigShowSimilarEntries} -\title{ -Find Similar Entries In Tables Of Datasets -} -\description{ -These functions help in finding similar entries in tables of supported datasets by comparing all entries with some given information.\cr -This is useful when dealing with complex configuration files and not sure if already support certain variables or datasets.\cr -At least one field must be provided in ConfigShowSimilarEntries(). Other fields can be unspecified and won't be taken into account. If more than one field is provided, sameness is avreaged over all provided fields and entries are sorted from higher average to lower. -} +\title{Find Similar Entries In Tables Of Datasets} \usage{ -ConfigShowSimilarEntries(configuration, dataset_name = NULL, - var_name = NULL, main_path = NULL, - file_path = NULL, nc_var_name = NULL, - suffix = NULL, varmin = NULL, - varmax = NULL, n_results = 10) +ConfigShowSimilarEntries(configuration, dataset_name = NULL, + var_name = NULL, main_path = NULL, file_path = NULL, + nc_var_name = NULL, suffix = NULL, varmin = NULL, varmax = NULL, + n_results = 10) } \arguments{ - \item{configuration}{ -Configuration object obtained either from ConfigFileCreate() or ConfigFileOpen(). - } - \item{dataset_name}{ -Optional dataset name to look for similars of. - } - \item{var_name}{ -Optional variable name to look for similars of. - } - \item{main_path}{ -Optional main path to look for similars of. - } - \item{file_path}{ -Optional file path to look for similars of. - } - \item{nc_var_name}{ -Optional variable name inside NetCDF file to look for similars of. - } - \item{suffix}{ -Optional suffix to look for similars of. - } - \item{varmin}{ -Optional variable minimum to look for similars of. - } - \item{varmax}{ -Optional variable maximum to look for similars of. - } - \item{n_results}{ -Top 'n_results' alike results will be shown only.\cr -Defaults to 10 in ConfigShowSimilarEntries() and to 5 in ConfigShowSimilarVars(). - } -} -\details{ -Sameness is calculated with string distances as specified by Simon White in [1]. +\item{configuration}{Configuration object obtained either from +ConfigFileCreate() or ConfigFileOpen().} + +\item{dataset_name}{Optional dataset name to look for similars of.} + +\item{var_name}{Optional variable name to look for similars of.} + +\item{main_path}{Optional main path to look for similars of.} + +\item{file_path}{Optional file path to look for similars of.} + +\item{nc_var_name}{Optional variable name inside NetCDF file to look for similars of.} + +\item{suffix}{Optional suffix to look for similars of.} + +\item{varmin}{Optional variable minimum to look for similars of.} + +\item{varmax}{Optional variable maximum to look for similars of.} + +\item{n_results}{Top 'n_results' alike results will be shown only. Defaults +to 10 in ConfigShowSimilarEntries() and to 5 in ConfigShowSimilarVars().} } \value{ These functions return information about the found matches. } -\seealso{ConfigApplyMatchingEntries, ConfigEditDefinition, ConfigEditEntry, ConfigFileOpen, ConfigShowSimilarEntries, ConfigShowTable} -\references{ -[1] Simon White, string seamness: http://www.catalysoft.com/articles/StrikeAMatch.html +\description{ +These functions help in finding similar entries in tables of supported +datasets by comparing all entries with some given information.\cr +This is useful when dealing with complex configuration files and not sure +if already support certain variables or datasets.\cr +At least one field must be provided in ConfigShowSimilarEntries(). +Other fields can be unspecified and won't be taken into account. If more +than one field is provided, sameness is avreaged over all provided fields +and entries are sorted from higher average to lower. } -\author{ -History:\cr -0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - First version -1.0 - 2015-11 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Removed grid column and storage formats +\details{ +Sameness is calculated with string distances as specified by Simon White +in [1]. } \examples{ # Create an empty configuration file @@ -73,15 +59,30 @@ configuration <- ConfigFileOpen(config_file) # table which will associate the experiment "ExampleExperiment2" and variable # "ExampleVariable" to some information about its location. configuration <- ConfigAddEntry(configuration, "experiments", "last", - "ExampleExperiment2", "ExampleVariable", - "/path/to/ExampleExperiment2/", - "ExampleVariable/ExampleVariable_$START_DATE$.nc") + "ExampleExperiment2", "ExampleVariable", + "/path/to/ExampleExperiment2/", + "ExampleVariable/ExampleVariable_$START_DATE$.nc") # Edit entry to generalize for any variable. Changing variable needs . configuration <- ConfigEditEntry(configuration, "experiments", 1, - var_name = "Var.*", - file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") + var_name = "Var.*", + file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") # Look for similar entries ConfigShowSimilarEntries(configuration, dataset_name = "Exper", - var_name = "Vari") + var_name = "Vari") + +} +\author{ +History:\cr + 0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - First version\cr + 1.0 - 2015-11 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Removed grid column and storage formats +} +\references{ +[1] Simon White, string seamness: + \url{http://www.catalysoft.com/articles/StrikeAMatch.html} +} +\seealso{ +ConfigApplyMatchingEntries, ConfigEditDefinition, + ConfigEditEntry, ConfigFileOpen, ConfigShowSimilarEntries, ConfigShowTable } \keyword{datagen} + diff --git a/man/ConfigShowTable.Rd b/man/ConfigShowTable.Rd index 0ba3fe28ba8827c442b40b51c2382f6d0fa19e90..a06b643e1f1cf9ba5909d923b704ef164b451bb8 100644 --- a/man/ConfigShowTable.Rd +++ b/man/ConfigShowTable.Rd @@ -1,37 +1,31 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ConfigShowTable.R \name{ConfigShowTable} -\alias{ConfigShowTable} \alias{ConfigShowDefinitions} -\title{ -Show Configuration Tables And Definitions -} -\description{ -These functions show the tables of supported datasets and definitions in a configuration object obtained via ConfigFileCreate() or ConfigFileOpen(). -} +\alias{ConfigShowTable} +\title{Show Configuration Tables And Definitions} \usage{ ConfigShowTable(configuration, dataset_type, line_numbers = NULL) + ConfigShowDefinitions(configuration) } \arguments{ - \item{configuration}{ -Configuration object obtained from ConfigFileCreate() or ConfigFileOpen(). - } - \item{dataset_type}{ -In ConfigShowTable(), 'dataset_type' tells whether the table to show is of experimental datasets or of observational datasets.\cr -Can take values 'experiments' or 'observations'. - } - \item{line_numbers}{ -'line_numbers' is an optional vector of numbers as long as the number of entries in the specified table.\cr -Intended for internal use. - } +\item{configuration}{Configuration object obtained from ConfigFileCreate() +or ConfigFileOpen().} + +\item{dataset_type}{In ConfigShowTable(), 'dataset_type' tells whether the +table to show is of experimental datasets or of observational datasets. +Can take values 'experiments' or 'observations'.} + +\item{line_numbers}{'line_numbers' is an optional vector of numbers as long +as the number of entries in the specified table. Intended for internal use.} } \value{ These functions return nothing. } -\seealso{ConfigApplyMatchingEntries, ConfigEditDefinition, ConfigEditEntry, ConfigFileOpen, ConfigShowSimilarEntries, ConfigShowTable} -\author{ -History:\cr -0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - First version -1.0 - 2015-11 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Removed grid column and storage formats +\description{ +These functions show the tables of supported datasets and definitions in a +configuration object obtained via ConfigFileCreate() or ConfigFileOpen(). } \examples{ # Create an empty configuration file @@ -43,15 +37,27 @@ configuration <- ConfigFileOpen(config_file) # table which will associate the experiment "ExampleExperiment2" and variable # "ExampleVariable" to some information about its location. configuration <- ConfigAddEntry(configuration, "experiments", "last", - "ExampleExperiment2", "ExampleVariable", - "/path/to/ExampleExperiment2/", - "ExampleVariable/ExampleVariable_$START_DATE$.nc") + "ExampleExperiment2", "ExampleVariable", + "/path/to/ExampleExperiment2/", + "ExampleVariable/ExampleVariable_$START_DATE$.nc") # Edit entry to generalize for any variable. Changing variable needs . configuration <- ConfigEditEntry(configuration, "experiments", 1, - var_name = ".*", - file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") + var_name = ".*", + file_path = "$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc") # Show tables, lists and definitions ConfigShowTable(configuration, 'experiments') ConfigShowDefinitions(configuration) + +} +\author{ +History:\cr + 0.1 - 2015-05 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - First version\cr + 1.0 - 2015-11 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Removed grid column and storage formats +} +\seealso{ +[ConfigApplyMatchingEntries()], [ConfigEditDefinition()], + [ConfigEditEntry()], [ConfigFileOpen()], [ConfigShowSimilarEntries()], + [ConfigShowTable()]. } \keyword{datagen} + diff --git a/man/Consist_Trend.Rd b/man/Consist_Trend.Rd index 6f964bf83bf3350c9ecb4f0952371ac55867eb28..a2911c6407fdcb730d5b6a07bb88cfb2b6b3f94f 100644 --- a/man/Consist_Trend.Rd +++ b/man/Consist_Trend.Rd @@ -1,48 +1,54 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Consist_Trend.R \name{Consist_Trend} \alias{Consist_Trend} -\title{ -Computes Trends Using Only Model Data For Which Observations Are Available -} -\description{ -Computes the trend coefficients for a time series by least square fitting, together with the associated error interval for both the observational and model data.\cr -Provides also the detrended observational and modeled data.\cr -By default, the trend is computed along the second dimension of the input array, which is expected to be the start date dimension. For arrays containing multiple model members, the user will first have to calculate the ensemble average using \code{Mean1Dim()} or elsewhise (see the example). -} +\title{Computes Trends Using Only Model Data For Which Observations Are Available} \usage{ Consist_Trend(var_exp, var_obs, interval = 1) } \arguments{ - \item{var_exp}{ -Ensemble mean of model hindcasts with dimensions:\cr - c(nmod/nexp, nsdates, nltime) up to\cr - c(nmod/nexp, nsdates, nltime, nlevel, nlat, nlon) - } - \item{var_obs}{ -Ensemble mean of observational data with dimensions:\cr - c(nobs, nsdates, nltime) up to\cr - c(nobs, nsdates, nltime, nlevel, nlat, nlon)\cr -Dimensions 2 to 6 should be the same as var_exp. - } - \item{interval}{ -Number of months/years between 2 start dates. Default = 1. The trends will be provided respectively in field unit per month or per year. - } +\item{var_exp}{Ensemble mean of model hindcasts with dimensions:\cr +c(nmod/nexp, nsdates, nltime) up to\cr +c(nmod/nexp, nsdates, nltime, nlevel, nlat, nlon)} + +\item{var_obs}{Ensemble mean of observational data with dimensions:\cr +c(nobs, nsdates, nltime) up to\cr +c(nobs, nsdates, nltime, nlevel, nlat, nlon)\cr +Dimensions 2 to 6 should be the same as var_exp.} + +\item{interval}{Number of months/years between 2 start dates. Default = 1. +The trends will be provided respectively in field unit per month or per year.} } \value{ - \item{$trend}{ -Trend coefficients of model and observational data with dimensions:\cr - c(nmod/nexp + nobs, 3, nltime) up to\cr - c(nmod/nexp + nobs, 3, nltime, nlevel, nlat, nlon)\cr -The length 3 dimension corresponds to the lower limit of the 95\% confidence interval, the slope of the trends and the upper limit of the 95\% confidence interval. - } - \item{$detrendedmod}{ -Same dimensions as var_exp with linearly detrended values of var_exp along the second = start date dimension. - } - \item{$detrendedobs}{ -Same dimensions as var_exp with linearly detrended values of var_obs along the second = start date dimension. - } +\item{$trend}{ + Trend coefficients of model and observational data with dimensions:\cr + c(nmod/nexp + nobs, 3, nltime) up to\cr + c(nmod/nexp + nobs, 3, nltime, nlevel, nlat, nlon)\cr + The length 3 dimension corresponds to the lower limit of the 95\% + confidence interval, the slope of the trends and the upper limit of the + 95\% confidence interval. +} +\item{$detrendedmod}{ + Same dimensions as var_exp with linearly detrended values of var_exp + along the second = start date dimension. +} +\item{$detrendedobs}{ + Same dimensions as var_exp with linearly detrended values of var_obs + along the second = start date dimension. +} +} +\description{ +Computes the trend coefficients for a time series by least square fitting, +together with the associated error interval for both the observational and +model data.\cr +Provides also the detrended observational and modeled data.\cr +By default, the trend is computed along the second dimension of the input +array, which is expected to be the start date dimension. For arrays +containing multiple model members, the user will first have to calculate +the ensemble average using \code{Mean1Dim()} or elsewhise (see the example). } \examples{ -# Load sample data as in Load() example: +#'# Load sample data as in Load() example: example(Load) clim <- Clim(sampleData$mod, sampleData$obs) ano_exp <- Ano(sampleData$mod, clim$clim_exp) @@ -54,20 +60,22 @@ smooth_ano_obs <- Smoothing(ano_obs, runmean_months, dim_to_smooth) dim_to_mean <- 2 # Mean along members years_between_startdates <- 5 trend <- Consist_Trend(Mean1Dim(smooth_ano_exp, dim_to_mean), - Mean1Dim(smooth_ano_obs, dim_to_mean), - years_between_startdates) + Mean1Dim(smooth_ano_obs, dim_to_mean), + years_between_startdates) PlotVsLTime(trend$trend, toptitle = "trend", ytitle = "K/(5 years)", - monini = 11, limits = c(-0.8, 0.8), listexp = c('CMIP5 IC3'), - listobs = c('ERSST'), biglab = FALSE, hlines = c(0), - fileout = 'tos_consist_trend.eps') + monini = 11, limits = c(-0.8, 0.8), listexp = c('CMIP5 IC3'), + listobs = c('ERSST'), biglab = FALSE, hlines = c(0), + fileout = 'tos_consist_trend.eps') PlotAno(InsertDim(trend$detrendedmod,2,1), InsertDim(trend$detrendedobs,2,1), - startDates, "Detrended tos anomalies", ytitle = 'K', - legends = 'ERSST', biglab = FALSE, fileout = 'tos_detrended_ano.eps') + startDates, "Detrended tos anomalies", ytitle = 'K', + legends = 'ERSST', biglab = FALSE, fileout = 'tos_detrended_ano.eps') + } \author{ History:\cr -0.1 - 2011-11 (V. Guemas, \email{vguemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to R CRAN + 0.1 - 2011-11 (V. Guemas, \email{vguemas@ic3.cat}) - Original code\cr + 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to R CRAN } \keyword{datagen} + diff --git a/man/Corr.Rd b/man/Corr.Rd index ae4b9f0005733d329afb75d1482ae67b5c1b15e5..fcaf149adf0f3193beb8373462f48e42f09ef64f 100644 --- a/man/Corr.Rd +++ b/man/Corr.Rd @@ -1,79 +1,89 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Corr.R \name{Corr} -\alias{Corr} \alias{.Corr} -\title{ -Computes the correlation coefficient between an array of forecasts and their corresponding observations. -} -\description{ -Calculates the correlation coefficient (Pearson, Kendall or Spearman) for an array of forecasts and observations. The input should be an array with dimensions c(no. of datasets, no. of start dates, no. of forecast times, no. of lons, no. of lats.), where the longitude and latitude dimensions are optional. The correlations are computed along the poscor dimension which should correspond to the startdate dimension. If compROW is given, the correlations are computed only if rows along the compROW dimension are complete between limits[1] and limits[2], i.e. there are no NAs between limits[1] and limits[2]. This option can be activated if the user wishes to account only for the forecasts for which observations are available at all leadtimes. \cr Default: limits[1] = 1 and limits[2] = length(compROW dimension).\cr The confidence interval is computed by a Fisher transformation.\cr The significance level relies on a one-sided student-T distribution.\cr We can modifiy the treshold of the test modifying siglev (default value=0.95). \cr -\cr -.Corr calculates the correlation between the ensemble mean and the observations, using an N by M matrix (exp) of forecasts and a vector of observations (obs) as input. -} +\alias{Corr} +\title{Computes the correlation coefficient between an array of forecasts and their corresponding observations} \usage{ -Corr(var_exp, var_obs, posloop = 1, poscor = 2, compROW = NULL, - limits = NULL, siglev = 0.95, method = 'pearson', - conf = TRUE, pval = TRUE) +Corr(var_exp, var_obs, posloop = 1, poscor = 2, compROW = NULL, + limits = NULL, siglev = 0.95, method = "pearson", conf = TRUE, + pval = TRUE) -.Corr(exp, obs, siglev = 0.95, method = 'pearson', - conf = TRUE, pval = TRUE) +.Corr(exp, obs, siglev = 0.95, method = "pearson", conf = TRUE, + pval = TRUE) } \arguments{ - \item{var_exp}{ -Array of experimental data. - } - \item{var_obs}{ -Array of observational data, same dimensions as var_exp except along posloop dimension, where the length can be nobs instead of nexp. - } - \item{posloop}{ -Dimension nobs and nexp. - } - \item{poscor}{ -Dimension along which correlation are to be computed (the dimension of the start dates). - } - \item{compROW}{ -Data taken into account only if (compROW)th row is complete.\cr Default = NULL. - } - \item{limits}{ -Complete between limits[1] & limits[2]. Default = NULL. - } - \item{siglev}{ -Significance level. Default = 0.95. - } - \item{method}{ -Type of correlation: 'pearson', 'spearman' or 'kendall'. Default='pearson' - } - \item{conf}{ -Whether to compute confidence intervals (default = 'TRUE') or not (FALSE). - } - \item{pval}{ -Whether to compute statistical significance p-value (default = 'TRUE') or not (FALSE). - } - \item{exp}{ -N by M matrix of N forecasts from M ensemble members. - } - \item{obs}{ -Vector of the corresponding observations of length N. - } +\item{var_exp}{Array of experimental data.} + +\item{var_obs}{Array of observational data, same dimensions as var_exp +except along posloop dimension, where the length can be nobs instead of nexp.} + +\item{posloop}{Dimension nobs and nexp.} + +\item{poscor}{Dimension along which correlation are to be computed (the +dimension of the start dates).} + +\item{compROW}{Data taken into account only if (compROW)th row is complete. +Default = NULL.} + +\item{limits}{Complete between limits[1] & limits[2]. Default = NULL.} + +\item{siglev}{Significance level. Default = 0.95.} + +\item{method}{Type of correlation: 'pearson', 'spearman' or 'kendall'. +Default='pearson'} + +\item{conf}{Whether to compute confidence intervals (default = 'TRUE') or +not (FALSE).} + +\item{pval}{Whether to compute statistical significance p-value (default = 'TRUE') +or not (FALSE).} + +\item{exp}{N by M matrix of N forecasts from M ensemble members.} + +\item{obs}{Vector of the corresponding observations of length N.} } \value{ -Corr: Array with dimensions :\cr c(# of datasets along posloop in var_exp, # of datasets along posloop in var_obs, 4, all other dimensions of var_exp & var_obs except poscor).\cr -The third dimension, of length 4 maximum, contains to the lower limit of the 95\% confidence interval, the correlation, the upper limit of the 95\% confidence interval and the 95\% significance level given by a one-sided T-test. If the p-value is disabled via \code{pval = FALSE}, this dimension will be of length 3. If the confidence intervals are disabled via \code{conf = FALSE}, this dimension will be of length 2. If both are disabled, this will be of length 2. \cr -\cr +Corr: Array with dimensions :\cr +c(# of datasets along posloop in var_exp, # of datasets along posloop in +var_obs, 4, all other dimensions of var_exp & var_obs except poscor).\cr +The third dimension, of length 4 maximum, contains to the lower limit of +the 95\% confidence interval, the correlation, the upper limit of the 95\% +confidence interval and the 95\% significance level given by a one-sided +T-test. If the p-value is disabled via \code{pval = FALSE}, this dimension +will be of length 3. If the confidence intervals are disabled via +\code{conf = FALSE}, this dimension will be of length 2. If both are +disabled, this will be of length 2. \cr\cr .Corr: - \itemize{ - \item{$corr}{ -The correlation statistic. - } - \item{$p_val}{ -Corresponds to the p values for the \code{siglev}\% (only present if \code{pval = TRUE}) for the correlation. - } - \item{$conf_low}{ -Corresponds to the upper limit of the \code{siglev}\% (only present if \code{conf = TRUE}) for the correlation. - } - \item{$conf_high}{ -Corresponds to the lower limit of the \code{siglev}\% (only present if \code{conf = TRUE}) for the correlation. - } - } + \itemize{ + \item{$corr}{The correlation statistic.} + \item{$p_val}{Corresponds to the p values for the \code{siglev}\% + (only present if \code{pval = TRUE}) for the correlation.} + \item{$conf_low}{Corresponds to the upper limit of the \code{siglev}\% + (only present if \code{conf = TRUE}) for the correlation.} + \item{$conf_high}{Corresponds to the lower limit of the \code{siglev}\% + (only present if \code{conf = TRUE}) for the correlation.} + } +} +\description{ +Calculates the correlation coefficient (Pearson, Kendall or Spearman) for +an array of forecasts and observations. The input should be an array with +dimensions c(no. of datasets, no. of start dates, no. of forecast times, +no. of lons, no. of lats.), where the longitude and latitude dimensions are +optional. The correlations are computed along the poscor dimension which +should correspond to the startdate dimension. If compROW is given, the +correlations are computed only if rows along the compROW dimension are +complete between limits[1] and limits[2], i.e. there are no NAs between +limits[1] and limits[2]. This option can be activated if the user wishes to +account only for the forecasts for which observations are available at all +leadtimes. \cr +Default: limits[1] = 1 and limits[2] = length(compROW dimension).\cr +The confidence interval is computed by a Fisher transformation.\cr +The significance level relies on a one-sided student-T distribution.\cr +We can modifiy the treshold of the test modifying siglev (default value=0.95).\cr\cr +.Corr calculates the correlation between the ensemble mean and the +observations, using an N by M matrix (exp) of forecasts and a vector of +observations (obs) as input. } \examples{ # Load sample data as in Load() example: @@ -90,32 +100,33 @@ dim_to_mean <- 2 # Mean along members required_complete_row <- 3 # Discard start dates which contain any NA lead-times leadtimes_per_startdate <- 60 corr <- Corr(Mean1Dim(smooth_ano_exp, dim_to_mean), - Mean1Dim(smooth_ano_obs, dim_to_mean), - compROW = required_complete_row, - limits = c(ceiling((runmean_months + 1) / 2), - leadtimes_per_startdate - floor(runmean_months / 2))) + Mean1Dim(smooth_ano_obs, dim_to_mean), + compROW = required_complete_row, + limits = c(ceiling((runmean_months + 1) / 2), + leadtimes_per_startdate - floor(runmean_months / 2))) PlotVsLTime(corr, toptitle = "correlations", ytitle = "correlation", - monini = 11, limits = c(-1, 2), listexp = c('CMIP5 IC3'), - listobs = c('ERSST'), biglab = FALSE, hlines = c(-1, 0, 1), - fileout = 'tos_cor.eps') + monini = 11, limits = c(-1, 2), listexp = c('CMIP5 IC3'), + listobs = c('ERSST'), biglab = FALSE, hlines = c(-1, 0, 1), + fileout = 'tos_cor.eps') # The following example uses veriApply combined with .Corr instead of Corr - \dontrun{ + \dontrun{ require(easyVerification) Corr2 <- s2dverification:::.Corr corr2 <- veriApply("Corr2", - smooth_ano_exp, - # see ?veriApply for how to use the 'parallel' option - Mean1Dim(smooth_ano_obs, dim_to_mean), - tdim = 3, ensdim = 2) - } + smooth_ano_exp, + # see ?veriApply for how to use the 'parallel' option + Mean1Dim(smooth_ano_obs, dim_to_mean), + tdim = 3, ensdim = 2) + } } \author{ History:\cr -0.1 - 2011-04 (V. Guemas, \email{vguemas at bsc.es}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Formatting to R CRAN\cr -1.1 - 2014-10 (M. Menegoz, \email{martin.menegoz at bsc.es}) - Adding siglev argument\cr -1.2 - 2015-03 (L.P. Caron, \email{louis-philippe.caron at bsc.es}) - Adding method argument\cr -1.3 - 2017-02 (A. Hunter, \email{alasdair.hunter at bsc.es}) - Adapted to veriApply() + 0.1 - 2011-04 (V. Guemas, \email{vguemas@bsc.es}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Formatting to R CRAN\cr +1.1 - 2014-10 (M. Menegoz, \email{martin.menegoz@bsc.es}) - Adding siglev argument\cr +1.2 - 2015-03 (L.P. Caron, \email{louis-philippe.caron@bsc.es}) - Adding method argument\cr +1.3 - 2017-02 (A. Hunter, \email{alasdair.hunter@bsc.es}) - Adapted to veriApply() } \keyword{datagen} + diff --git a/man/EOF.Rd b/man/EOF.Rd index 7c914e1570c2c415ae41d570448d0385290aa461..bd0b31e43a41999b50a7f9fe93d9f3ff9a4a00c7 100644 --- a/man/EOF.Rd +++ b/man/EOF.Rd @@ -1,123 +1,122 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/EOF.R \name{EOF} \alias{EOF} -\title{ -Area-Weighted Empirical Orthogonal Function Analysis Using SVD -} -\description{ -Performs an area-weighted EOF analysis using SVD based on a covariance matrix -by default, based on the correlation matrix if \code{corr} argument is set to -\code{TRUE}. -} +\title{Area-Weighted Empirical Orthogonal Function Analysis Using SVD} \usage{ EOF(ano, lon, lat, neofs = 15, corr = FALSE) } \arguments{ - \item{ano}{ -Array of anomalies with dimensions (number of timesteps, number of latitudes, -number of longitudes). - } - \item{lon}{ -Vector of longitudes of \code{ano}. - } - \item{lat}{ -Vector of latitudes of \code{ano}. - } - \item{neofs}{ -Number of modes to be kept. Default = 15. - } - \item{corr}{ -Whether to base on a correlation matrix (\code{TRUE}) or on a covariance -matrix (default, \code{FALSE}). - } +\item{ano}{Array of anomalies with dimensions (number of timesteps, +number of latitudes, number of longitudes).} + +\item{lon}{Vector of longitudes of \code{ano}.} + +\item{lat}{Vector of latitudes of \code{ano}.} + +\item{neofs}{Number of modes to be kept. Default = 15.} + +\item{corr}{Whether to base on a correlation matrix (\code{TRUE}) or on a +covariance matrix (default, \code{FALSE}).} } \value{ - \item{EOFs}{ -An array of EOF patterns normalized to 1 (unitless) with dimensions (number of -modes, number of latitudes, number of longitues). Multiplying \code{EOFs} by -\code{PCs} gives the original reconstructed field. - } - \item{PCs}{ -An array of pincipal components with the units of the original field to the -power of 2, with dimensions (number of time steps, number of modes). \code{PCs} -contains already the percentage of explained variance so, to reconstruct the -original field it's only needed to multiply \code{EOFs} by \code{PCs}. - } - \item{var}{ -Percentage (%) of variance fraction of total variance explained by each mode -(number of modes). - } - \item{mask}{ -Mask with dimensions (number of latitudes, number of lonfitudes). - } - \item{wght}{ -Weights with dimensions (number of latitudes, number of longitudes). - } +\item{EOFs}{ + An array of EOF patterns normalized to 1 (unitless) with dimensions + (number of modes, number of latitudes, number of longitues). + Multiplying \code{EOFs} by \code{PCs} gives the original reconstructed field. +} +\item{PCs}{ + An array of pincipal components with the units of the original field to + the power of 2, with dimensions (number of time steps, number of modes). + \code{PCs} contains already the percentage of explained variance so, + to reconstruct the original field it's only needed to multiply \code{EOFs} + by \code{PCs}. +} +\item{var}{ + Percentage (%) of variance fraction of total variance explained by each + mode (number of modes). +} +\item{mask}{ + Mask with dimensions (number of latitudes, number of longitudes). +} +\item{wght}{ + Weights with dimensions (number of latitudes, number of longitudes). +} +} +\description{ +Performs an area-weighted EOF analysis using SVD based on a covariance matrix +by default, based on the correlation matrix if \code{corr} argument is set to +\code{TRUE}. } \examples{ # See examples on Load() to understand the first lines in this example - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') expA <- list(name = 'experiment', path = file.path(data_path, - 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', - '$VAR_NAME$_$START_DATE$.nc')) + 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', + '$VAR_NAME$_$START_DATE$.nc')) obsX <- list(name = 'observation', path = file.path(data_path, - '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', - '$VAR_NAME$_$YEAR$$MONTH$.nc')) + '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', + '$VAR_NAME$_$YEAR$$MONTH$.nc')) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(expA), list(obsX), startDates, - leadtimemin = 1, leadtimemax = 4, output = 'lonlat', - latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) - } - \dontshow{ + leadtimemin = 1, leadtimemax = 4, output = 'lonlat', + latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) + } + \dontshow{ startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - leadtimemin = 1, - leadtimemax = 4, - output = 'lonlat', - latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } + c('observation'), startDates, + leadtimemin = 1, + leadtimemax = 4, + output = 'lonlat', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } # This example computes the EOFs along forecast horizons and plots the one that # explains the greatest amount of variability. The example data is very low # resolution so it does not make a lot of sense. ano <- Ano_CrossValid(sampleData$mod, sampleData$obs) eof <- EOF(Mean1Dim(ano$ano_exp, 2)[1, , 1, , ], sampleData$lon, sampleData$lat) PlotEquiMap(eof$EOFs[1, , ], sampleData$lon, sampleData$lat) + } \author{ History:\cr -0.1 - 2012-10 (F. Lienert, \email{fabian.lienert at ic3.cat}) - Original\cr +0.1 - 2012-10 (F. Lienert, \email{fabian.lienert@ic3.cat}) - Original code, inspired by R. Benestad's EOF() in R package clim.pact.\cr -0.2 - 2014-03 (Lauriane Batte, \email{lauriane.batte at ic3.cat}) - Bug-fixes:\cr - 1- Reversion of latitudes in the weights\cr - 2- Correlation matrix was used instead of covariance\cr - 3- Double use of the weights\cr -0.3 - 2014-03 (Virginie Guemas, \email{virginie.guemas at bsc.es}) - Bug-fixes:\cr - 1- Weight computation - division by sum of cos(lat)\cr - 2- Shuffling of EOFs in EOF.2 intermediate vector\cr - 3- Crash when neofs = 1 sorted out\cr - 4- Crash when neofs > nt sorted out\cr -0.4 - 2014-03 (Lauriane Batte, \email{lauriane.batte at ic3.cat}) - Fixes:\cr - 1- BIG cleanup of code and clarification\cr - 2- Reduction of the number of transpositions and associated bug-fixes\cr - 4- Remove of the obsolete LINPACK options\cr -0.5 - 2014-04 (Virginie Guemas, \email{virginie.guemas at bsc.es}) - Fixes:\cr - 1- Bug-fix in dimensions handling EOF composition restitutes now the\ +0.2 - 2014-03 (Lauriane Batte, \email{lauriane.batte@ic3.cat}) - Bug-fixes:\cr + 1- Reversion of latitudes in the weights\cr + 2- Correlation matrix was used instead of covariance\cr + 3- Double use of the weights\cr +0.3 - 2014-03 (Virginie Guemas, \email{virginie.guemas@bsc.es}) - Bug-fixes:\cr + 1- Weight computation - division by sum of cos(lat)\cr + 2- Shuffling of EOFs in EOF.2 intermediate vector\cr + 3- Crash when neofs = 1 sorted out\cr + 4- Crash when neofs > nt sorted out\cr +0.4 - 2014-03 (Lauriane Batte, \email{lauriane.batte@ic3.cat}) - Fixes:\cr + 1- BIG cleanup of code and clarification\cr + 2- Reduction of the number of transpositions and associated bug-fixes\cr + 4- Remove of the obsolete LINPACK options\cr +0.5 - 2014-04 (Virginie Guemas, \email{virginie.guemas@bsc.es}) - Fixes:\cr + 1- Bug-fix in dimensions handling EOF composition restitutes now the original field in all cases\cr - 2- Simplification of the convention transpose\cr - 3- Options to use the correlation matrix rather than the + 2- Simplification of the convention transpose\cr + 3- Options to use the correlation matrix rather than the covariance matrix\cr - 4- Security checks\cr - 5- New normalization of PCs so that PC*EOF only reconstruct the + 4- Security checks\cr + 5- New normalization of PCs so that PC*EOF only reconstruct the original file\cr - 6- Weights = sqrt(cos(lat)) for ano so that covariance matrice + 6- Weights = sqrt(cos(lat)) for ano so that covariance matrice weighted by cos(lat)\cr - 7- Division of EOF by weights so that the reconstruction is simply + 7- Division of EOF by weights so that the reconstruction is simply EOF * PC\cr -1.0 - 2016-03 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Formatting to R CRAN +1.0 - 2016-03 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Formatting to R CRAN +} +\seealso{ +ProjectField, NAO, PlotBoxWhisker } -\seealso{ProjectField, NAO, PlotBoxWhisker} \keyword{datagen} + diff --git a/man/Enlarge.Rd b/man/Enlarge.Rd index ab700e686947a46ce0e434bc74d8faf9f0310295..76f5cccf81c2f0da4c788adfc437ebb2c9f4c408 100644 --- a/man/Enlarge.Rd +++ b/man/Enlarge.Rd @@ -1,24 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Enlarge.R \name{Enlarge} \alias{Enlarge} -\title{ -Extends The Number Of Dimensions of A Matrix -} -\description{ -Extends the number of dimensions of var to numdims (the added dimensions have length 1). -} +\title{Extends The Number Of Dimensions of A Matrix} \usage{ Enlarge(var, numdims) } \arguments{ - \item{var}{ -Matrix to be extended. - } - \item{numdims}{ -Output number of dimensions. - } +\item{var}{Matrix to be extended.} + +\item{numdims}{Output number of dimensions.} } \value{ -Extended matrix. +Output number of dimensions. +} +\description{ +Extends the number of dimensions of var to numdims (the added dimensions +have length 1). } \examples{ data <- array(1, c(2, 2, 3)) @@ -26,8 +24,9 @@ print(dim(Enlarge(data, 5))) } \author{ History:\cr -0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to R CRAN\cr -1.1 - 2015-03 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Improved\cr + 0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr + 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to R CRAN\cr + 1.1 - 2015-03 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Improved\cr } \keyword{datagen} + diff --git a/man/Eno.Rd b/man/Eno.Rd index 8aed1d5b2316317a5fd202981dac038514dbfd28..ba4f2088a3b8de234afe763c71bc401dfd70f4b1 100644 --- a/man/Eno.Rd +++ b/man/Eno.Rd @@ -1,58 +1,58 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Eno.R \name{Eno} \alias{Eno} -\title{ -Computes Effective Sample Size With Classical Method -} -\description{ -Computes the effective number of independent values along the posdim dimension of a matrix.\cr -This effective number of independent observations can be used in statistical/inference tests.\cr -Based on eno function from Caio Coelho from rclim.txt. -} +\title{Computes Effective Sample Size With Classical Method} \usage{ Eno(obs, posdim) } \arguments{ - \item{obs}{ -Matrix of any number of dimensions up to 10. - } - \item{posdim}{ -Dimension along which to compute the effective sample size. - } +\item{obs}{Matrix of any number of dimensions up to 10.} + +\item{posdim}{Dimension along which to compute the effective sample size.} } \value{ Same dimensions as var but without the posdim dimension. } +\description{ +Computes the effective number of independent values along the posdim +dimension of a matrix.\cr +This effective number of independent observations can be used in +statistical/inference tests.\cr +Based on eno function from Caio Coelho from rclim.txt. +} \examples{ # See examples on Load() to understand the first lines in this example - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') exp <- list( - name = 'experiment', - path = file.path(data_path, 'model/$EXP_NAME$/monthly_mean', - '$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATES$.nc') - ) + name = 'experiment', + path = file.path(data_path, 'model/$EXP_NAME$/monthly_mean', + '$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATES$.nc') + ) obs <- list( - name = 'observation', - path = file.path(data_path, 'observation/$OBS_NAME$/monthly_mean', - '$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') - ) + name = 'observation', + path = file.path(data_path, 'observation/$OBS_NAME$/monthly_mean', + '$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') + ) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(exp), list(obs), startDates, - leadtimemin = 1, leadtimemax = 4, output = 'lonlat', - latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) - } - \dontshow{ + leadtimemin = 1, leadtimemax = 4, output = 'lonlat', + latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) + } + \dontshow{ startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - output = 'lonlat', - latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } + c('observation'), startDates, + output = 'lonlat', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } sampleData$mod <- Season(sampleData$mod, 4, 11, 1, 12) eno <- Eno(sampleData$mod[1, 1, , 1, , ], 1) PlotEquiMap(eno, sampleData$lon, sampleData$lat) + } \author{ History:\cr @@ -60,3 +60,4 @@ History:\cr 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to R CRAN } \keyword{datagen} + diff --git a/man/EnoNew.Rd b/man/EnoNew.Rd index 20ed93214ceb513402f135727903055c2fa12c78..cc2de7608632685dc4fdb75128adbfb94cfc7492 100644 --- a/man/EnoNew.Rd +++ b/man/EnoNew.Rd @@ -1,55 +1,70 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/EnoNew.R \name{EnoNew} \alias{EnoNew} \title{Computes Effective Sample Size Following Guemas et al, BAMS, 2013b} -\description{ -This function computes the effective number of independent values in the xdata array following the method described in Guemas V., Auger L., Doblas-Reyes F., JAMC, 2013. \code{EnoNew} provides similar functionality to \code{Eno} but with the added options to remove the linear trend or filter the frequency.} \usage{ EnoNew(xdata, detrend = FALSE, filter = FALSE) } \arguments{ - \item{xdata}{a numeric vector} - \item{detrend}{should the linear trend be removed from the data prior to the estimation of the equivalent number of independent values.} - \item{filter}{should a filtering of the frequency peaks be applied prior to the estimation of the equivalent number of independant data.} +\item{xdata}{A numeric vector.} + +\item{detrend}{Should the linear trend be removed from the data prior to +the estimation of the equivalent number of independent values.} + +\item{filter}{Should a filtering of the frequency peaks be applied prior +to the estimation of the equivalent number of independant data.} +} +\description{ +This function computes the effective number of independent values in the +xdata array following the method described in +Guemas V., Auger L., Doblas-Reyes F., JAMC, 2013. \code{EnoNew} provides +similar functionality to \code{Eno} but with the added options to remove +the linear trend or filter the frequency. } \examples{ # See examples on Load() to understand the first lines in this example - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') exp <- list( - name = 'experiment', - path = file.path(data_path, 'model/$EXP_NAME$/monthly_mean', - '$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATES$.nc') - ) + name = 'experiment', + path = file.path(data_path, 'model/$EXP_NAME$/monthly_mean', + '$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATES$.nc') + ) obs <- list( - name = 'observation', - path = file.path(data_path, 'observation/$OBS_NAME$/monthly_mean', - '$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') - ) + name = 'observation', + path = file.path(data_path, 'observation/$OBS_NAME$/monthly_mean', + '$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') + ) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(exp), list(obs), startDates, - leadtimemin = 1, leadtimemax = 4, output = 'lonlat', - latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) - } - \dontshow{ + leadtimemin = 1, leadtimemax = 4, output = 'lonlat', + latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) + } + \dontshow{ startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - leadtimemin = 1, - leadtimemax = 4, - output = 'lonlat', - latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } + c('observation'), startDates, + leadtimemin = 1, + leadtimemax = 4, + output = 'lonlat', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } eno <- EnoNew(sampleData$mod[1, 1, , 1, 2, 3]) print(eno) -} -\references{ -Guemas V, Auger L, Doblas-Reyes FJ, Rust H, Ribes A, 2014, Dependencies in Statistical Hypothesis Tests for Climate Time Series. Bulletin of the American Meteorological Society, 95 (11), 1666-1667. + } \author{ History:\cr 0.1 - 2012-06 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN } +\references{ +Guemas V, Auger L, Doblas-Reyes FJ, Rust H, Ribes A, 2014, Dependencies in + Statistical Hypothesis Tests for Climate Time Series. Bulletin of the + American Meteorological Society, 95 (11), 1666-1667. +} \keyword{datagen} + diff --git a/man/Filter.Rd b/man/Filter.Rd index bb1bcf44f79f867407eeae6d0854e8158c8aa15a..3ee7df89e18fde582ed2f6e951736a60e5169f0b 100644 --- a/man/Filter.Rd +++ b/man/Filter.Rd @@ -1,34 +1,44 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Filter.R \name{Filter} \alias{Filter} \title{Filter Frequency Peaks From An Array} -\description{ -This function filters out the selected frequency from a time series.\cr -The filtering is performed by dichotomy, seeking for a frequency around the parameter \code{freq} and the phase that maximizes the signal to subtract from the time series.\cr -The maximization of the signal to subtract relies on a minimization of the mean square differences between the time series (xdata) and the cosine of the specified frequency and phase. -} \usage{ Filter(xdata, freq) } \arguments{ - \item{xdata}{Array to be filtered.} - \item{freq}{Frequency to filter.} +\item{xdata}{Array to be filtered.} + +\item{freq}{Frequency to filter.} +} +\value{ +Filtered Array. +} +\description{ +This function filters out the selected frequency from a time series.\cr +The filtering is performed by dichotomy, seeking for a frequency around +the parameter \code{freq} and the phase that maximizes the signal to subtract +from the time series.\cr +The maximization of the signal to subtract relies on a minimization of the +mean square differences between the time series (xdata) and the cosine of +the specified frequency and phase. } -\value{Filtered Array} \examples{ # Load sample data as in Load() example: example(Load) ensmod <- Mean1Dim(sampleData$mod, 2) for (jstartdate in 1:3) { - spectrum <- Spectrum(ensmod[1, jstartdate, ]) - for (jlen in 1:dim(spectrum)[1]) { - if (spectrum[jlen, 2] > spectrum[jlen, 4]) { - ensmod[1, jstartdate, ] <- Filter(ensmod[1, jstartdate, ], - spectrum[jlen, 1]) - } - } + spectrum <- Spectrum(ensmod[1, jstartdate, ]) + for (jlen in 1:dim(spectrum)[1]) { + if (spectrum[jlen, 2] > spectrum[jlen, 4]) { + ensmod[1, jstartdate, ] <- Filter(ensmod[1, jstartdate, ], + spectrum[jlen, 1]) + } + } } PlotAno(InsertDim(ensmod, 2, 1), sdates = startDates, fileout = - 'filtered_ensemble_mean.eps') + 'filtered_ensemble_mean.eps') + } \author{ History:\cr @@ -36,3 +46,4 @@ History:\cr 1.0 - 2012-02 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN } \keyword{datagen} + diff --git a/man/FitAcfCoef.Rd b/man/FitAcfCoef.Rd index 73db6dfc96fe820d76c583082d6e2db476d50f5c..6ca5144422f5d4ed43c94753bd58c50013e2fc5d 100644 --- a/man/FitAcfCoef.Rd +++ b/man/FitAcfCoef.Rd @@ -1,25 +1,41 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/FitAcfCoef.R \name{FitAcfCoef} \alias{FitAcfCoef} \title{Fits an AR1 AutoCorrelation Function Using the Cardano Formula} -\description{ -This function finds the minimum point of the fourth order polynom (a - x)2 + 0.25(b - x2)2 written to fit the two autoregression coefficients a and b.\cr -A consequence of the Cardano formula is that, provided a and b are in [0 1], the problem is well posed, delta > 0 and there is only one minimum.\cr\cr -This function is called in Alpha() to minimize the mean square differences between the theoretical autocorrelation function of an AR1 and the first guess of the estimated autocorrelation function estacf, using only the first two lags.} -\usage{FitAcfCoef(a, b)} +\usage{ +FitAcfCoef(a, b) +} \arguments{ - \item{a}{Coefficient a : first estimate of the autocorrelation at lag 1} - \item{b}{Coefficient b : first estimate of the autocorrelation at lag 2} +\item{a}{Coefficient a : first estimate of the autocorrelation at lag 1.} + +\item{b}{Coefficient b : first estimate of the autocorrelation at lag 2.} +} +\value{ +Best estimate of the autocorrelation at lag 1. +} +\description{ +This function finds the minimum point of the fourth order polynom +(a - x)2 + 0.25(b - x2)2 written to fit the two autoregression coefficients +a and b.\cr +A consequence of the Cardano formula is that, provided a and b are in [0 1], +the problem is well posed, delta > 0 and there is only one minimum.\cr\cr +This function is called in Alpha() to minimize the mean square differences +between the theoretical autocorrelation function of an AR1 and the first +guess of the estimated autocorrelation function estacf, using only the +first two lags. } -\value{Best estimate of the autocorrelation at lag 1} \examples{ series <- GenSeries(1000, 0.35, 2, 1) estacf <- acf(series[951:1000], plot = FALSE)$acf alpha <- FitAcfCoef(max(estacf[2], 0), max(estacf[3], 0)) print(alpha) + } \author{ History:\cr 0.1 - 2012-06 (L. Auger, \email{ludovic.auger@meteo.fr}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{datagen} + diff --git a/man/FitAutocor.Rd b/man/FitAutocor.Rd index d5031fdb74167cc7e3fcf770e835d2c548c965f9..ff3ab9433d2460d631c384a80c358945d364d48a 100644 --- a/man/FitAutocor.Rd +++ b/man/FitAutocor.Rd @@ -1,16 +1,28 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/FitAutocor.R \name{FitAutocor} \alias{FitAutocor} \title{Fits an AR1 Autocorrelation Function Using Dichotomy} -\description{This function fits the theoretical autocorrelation function of an AR1 to the first guess of the estimated autocorrelation function estacf containing any number of lags. The fitting relies on a dichotomial minimisation of the mean square differences between both autocorrelation functions. It returns the autocorrelation at lag 1 of the fitted AR1 process.} \usage{ FitAutocor(estacf, window = c(-1, 1), prec = 0.01) } \arguments{ - \item{estacf}{First guess for the autocorrelation function} - \item{window}{Interval in which the autocorrelation at lag 1 should be found.} - \item{prec}{Precision to which the autocorrelation function at lag 1 is to be estimated.} +\item{estacf}{First guess for the autocorrelation function.} + +\item{window}{Interval in which the autocorrelation at lag 1 should be found.} + +\item{prec}{Precision to which the autocorrelation function at lag 1 is to be estimated.} +} +\value{ +Best estimate of the autocorrelation at lag 1. +} +\description{ +This function fits the theoretical autocorrelation function of an AR1 to +the first guess of the estimated autocorrelation function estacf containing +any number of lags. The fitting relies on a dichotomial minimisation of the +mean square differences between both autocorrelation functions. It returns +the autocorrelation at lag 1 of the fitted AR1 process. } -\value{Best estimate of the autocorrelation at lag 1} \examples{ series <- GenSeries(1000, 0.35, 2, 1) estacf <- acf(series[951:1000], plot = FALSE)$acf @@ -19,7 +31,8 @@ print(alpha) } \author{ History:\cr -0.1 - 2012-02 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +0.1 - 2012-02 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{datagen} + diff --git a/man/GenSeries.Rd b/man/GenSeries.Rd index e616d6a13c528366040c48764317a937bdec797d..9a49ed9d222a53effea4e3f1f73592778047e186 100644 --- a/man/GenSeries.Rd +++ b/man/GenSeries.Rd @@ -1,24 +1,37 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/GenSeries.R \name{GenSeries} \alias{GenSeries} \title{Generates An AR1 Time Series} -\description{This function generates AR1 processes containing n data points, where alpha is the autocorrelation at lag 1, and the mean and standard deviation are specified by the mean and std arguments.} \usage{ GenSeries(n, alpha, mean, std) } \arguments{ - \item{n}{Length of the timeseries to be generated.} - \item{alpha}{Autocorrelation at lag 1.} - \item{mean}{Mean of the data.} - \item{std}{Standard deviation of the data.} +\item{n}{Length of the timeseries to be generated.} + +\item{alpha}{Autocorrelation at lag 1.} + +\item{mean}{Mean of the data.} + +\item{std}{Standard deviation of the data.} +} +\value{ +AR1 timeseries. +} +\description{ +This function generates AR1 processes containing n data points, where alpha +is the autocorrelation at lag 1, and the mean and standard deviation are +specified by the mean and std arguments. } -\value{AR1 timeseries} \examples{ series <- GenSeries(1000, 0.35, 2, 1) plot(series, type = 'l') + } \author{ History:\cr 0.1 - 2012-04 (L. Auger, \email{ludovic.auger@meteo.fr}) - Original code\cr -1.0 - 2012-04 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +1.0 - 2012-04 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{datagen} + diff --git a/man/Histo2Hindcast.Rd b/man/Histo2Hindcast.Rd index 06cf92e5d6da704840f931b1db5fbca59b8df168..af494f1a481e798005cc3d33719739c6a799247d 100644 --- a/man/Histo2Hindcast.Rd +++ b/man/Histo2Hindcast.Rd @@ -1,78 +1,80 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Histo2Hindcast.R \name{Histo2Hindcast} \alias{Histo2Hindcast} -\title{ -Chunks Long Simulations For Comparison With Hindcasts -} -\description{ -This function reorganizes a long run (historical typically) with only one start date into chunks corresponding to a set of start dates. The expected input structure is the one output from \code{Load()} with 4 to 7 dimensions. -} +\title{Chunks Long Simulations For Comparison With Hindcasts} \usage{ Histo2Hindcast(varin, sdatesin, sdatesout, nleadtimesout) } \arguments{ - \item{varin}{ -Array of model or observational data with dimensions:\cr - c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltimes) up to\cr - c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltimes, nlevel, nlat, nlon) - } - \item{sdatesin}{ -Start date of the input matrix 'YYYYMMDD'. - } - \item{sdatesout}{ -List of start dates of the output matrix c('YYYYMMDD', 'YYYYMMDD', ...). - } - \item{nleadtimesout}{ -Number of leadtimes in the output matrix. - } +\item{varin}{Array of model or observational data with dimensions:\cr +c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltimes) up to\cr +c(nmod/nexp/nobs, nmemb/nparam, nsdates, nltimes, nlevel, nlat, nlon)} + +\item{sdatesin}{Start date of the input matrix 'YYYYMMDD'.} + +\item{sdatesout}{List of start dates of the output matrix +c('YYYYMMDD', 'YYYYMMDD', ...).} + +\item{nleadtimesout}{Number of leadtimes in the output matrix.} } \value{ -An array with the same number of dimensions as varin, the same dimensions 1 and 2 and potentially the same dimensions 5 to 7. Dimensions 3 and 4 are set by the arguments sdatesout and nleadtimesout. +An array with the same number of dimensions as varin, the same +dimensions 1 and 2 and potentially the same dimensions 5 to 7. Dimensions +3 and 4 are set by the arguments sdatesout and nleadtimesout. +} +\description{ +This function reorganizes a long run (historical typically) with only one +start date into chunks corresponding to a set of start dates. The expected +input structure is the one output from \code{Load()} with 4 to 7 dimensions. } \examples{ # See examples on Load() to understand the first lines in this example - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') exp <- list( - name = 'experiment', - path = file.path(data_path, 'model/$EXP_NAME$/monthly_mean', - '$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATES$.nc') - ) + name = 'experiment', + path = file.path(data_path, 'model/$EXP_NAME$/monthly_mean', + '$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATES$.nc') + ) obs <- list( - name = 'observation', - path = file.path(data_path, 'observation/$OBS_NAME$/monthly_mean', - '$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') - ) + name = 'observation', + path = file.path(data_path, 'observation/$OBS_NAME$/monthly_mean', + '$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') + ) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(exp), list(obs), startDates, - leadtimemin = 1, leadtimemax = 4, output = 'lonlat', - latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) - } - \dontshow{ + leadtimemin = 1, leadtimemax = 4, output = 'lonlat', + latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) + } + \dontshow{ startDates <- c('19901101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - leadtimemin = 1, - leadtimemax = 4, - output = 'areave', - latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } + c('observation'), startDates, + leadtimemin = 1, + leadtimemax = 4, + output = 'areave', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } start_dates_out <- c('19901101', '19911101', '19921101', '19931101', '19941101') leadtimes_per_startdate <- 12 experimental_data <- Histo2Hindcast(sampleData$mod, startDates[1], - start_dates_out, leadtimes_per_startdate) + start_dates_out, leadtimes_per_startdate) observational_data <- Histo2Hindcast(sampleData$obs, startDates[1], - start_dates_out, leadtimes_per_startdate) + start_dates_out, leadtimes_per_startdate) PlotAno(experimental_data, observational_data, start_dates_out, - toptitle = paste('anomalies reorganized into shorter chunks'), - ytitle = 'K', fileout='tos_histo2hindcast.eps') + toptitle = paste('anomalies reorganized into shorter chunks'), + ytitle = 'K', fileout='tos_histo2hindcast.eps') + } \author{ History:\cr -0.1 - 2012-11 (V. Guemas, \email{vguemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +0.1 - 2012-11 (V. Guemas, \email{vguemas@ic3.cat}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{datagen} + diff --git a/man/IniListDims.Rd b/man/IniListDims.Rd index 0af0253c16911fa06ee6c8ee364383460e45d50f..422a4c76089e9398225a5b7b438b494ee30635d7 100644 --- a/man/IniListDims.Rd +++ b/man/IniListDims.Rd @@ -1,27 +1,32 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/IniListDims.R \name{IniListDims} \alias{IniListDims} -\title{ -Creates A List Of Integer Ranges -} -\description{ -This function generates a list of arrays containing integers greater than or equal to 1. This list of arrays is used in other functions as a list of indices of the elements of the matrices. -} +\title{Creates A List Of Integer Ranges} \usage{ IniListDims(dims, lenlist) } \arguments{ - \item{dims}{ -The dimensions of a matrix for which we need the possible indices for each dimension. For exemple, if the dimensions sent are c(3,2,5), the following list of arrays will be generated:\cr - list(c(1:3), c(1:2), c(1:5)) - } - \item{lenlist}{ -'lenlist' is the length of the list because the list will be complemented above length(dims) by arrays of length 1.\cr -For example, if lenlist is set to 7, the previous list of arrays will be extended to:\cr - list(c(1:3), c(1:2), c(1:5), 1, 1, 1, 1) - } +\item{dims}{The dimensions of a matrix for which we need the possible +indices for each dimension. For exemple, if the dimensions sent are +c(3,2,5), the following list of arrays will be generated:\cr +list(c(1:3), c(1:2), c(1:5)).} + +\item{lenlist}{'lenlist' is the length of the list because the list will +be complemented above length(dims) by arrays of length 1.\cr +For example, if lenlist is set to 7, the previous list of arrays will be +extended to:\cr +list(c(1:3), c(1:2), c(1:5), 1, 1, 1, 1).} } \value{ -A list with lenlist elements, each with arrays with integers from 1 to the numbers in dims array and with only 1 for the dimensions above length(dims). +A list with lenlist elements, each with arrays with integers from 1 + to the numbers in dims array and with only 1 for the dimensions above + length(dims). +} +\description{ +This function generates a list of arrays containing integers greater than or +equal to 1. This list of arrays is used in other functions as a list of +indices of the elements of the matrices. } \examples{ indices <- IniListDims(c(2, 2, 4, 3), 6) @@ -34,3 +39,4 @@ History:\cr 1.1 - 2015-03 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Improved } \keyword{datagen} + diff --git a/man/InsertDim.Rd b/man/InsertDim.Rd index 6b08a5830d50125f3a11633fba3de67dd51f1d74..4cdc5377dc69001eed6ff3cfe93192d5086ecb08 100644 --- a/man/InsertDim.Rd +++ b/man/InsertDim.Rd @@ -1,33 +1,31 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/InsertDim.R \name{InsertDim} \alias{InsertDim} -\title{ -Adds A Dimension To An Array -} -\description{ -Inserts an extra dimension into an array at position 'posdim' with length 'lendim' and which correspond to 'lendim' repetitions of the 'var' array. -} +\title{Adds A Dimension To An Array} \usage{ InsertDim(var, posdim, lendim) } \arguments{ - \item{var}{ -Matrix to which a dimension should be added. - } - \item{posdim}{ -Position of the new dimension. - } - \item{lendim}{ -Length of the new dimension. - } +\item{var}{Matrix to which a dimension should be added.} + +\item{posdim}{Position of the new dimension.} + +\item{lendim}{Length of the new dimension.} } \value{ Matrix with the added dimension. } +\description{ +Inserts an extra dimension into an array at position 'posdim' with length +'lendim' and which correspond to 'lendim' repetitions of the 'var' array. +} \examples{ a <- array(rnorm(15), dim = c(3, 1, 5, 1)) print(dim(a)) print(dim(a[, , , ])) print(dim(InsertDim(InsertDim(a[, , , ], 2, 1), 4, 1))) + } \author{ History:\cr @@ -36,3 +34,4 @@ History:\cr 1.1 - 2015-03 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Improvements } \keyword{datagen} + diff --git a/man/LeapYear.Rd b/man/LeapYear.Rd index faf414567b68a50863a5ebe56f51a95cd141e26c..12b02b49a48ed2ec974e35b24d94fbd803aa40aa 100644 --- a/man/LeapYear.Rd +++ b/man/LeapYear.Rd @@ -1,20 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/LeapYear.R \name{LeapYear} \alias{LeapYear} \title{Checks Whether A Year Is Leap Year} -\description{ -This function tells whether a year is a leap year or not. -} \usage{ LeapYear(year) } \arguments{ - \item{year}{ -A numeric value indicating the year in the Gregorian calendar. - } +\item{year}{A numeric value indicating the year in the Gregorian calendar.} } \value{ Boolean telling whether the year is a leap year or not. } +\description{ +This function tells whether a year is a leap year or not. +} \examples{ print(LeapYear(1990)) print(LeapYear(1991)) @@ -23,7 +23,8 @@ print(LeapYear(1993)) } \author{ History:\cr -0.1 - 2011-03 (V. Guemas, \email{vguemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +0.1 - 2011-03 (V. Guemas, \email{vguemas@ic3.cat}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{datagen} + diff --git a/man/Load.Rd b/man/Load.Rd index eef60299dab3bb0e60216aee4cb8bcd63109759e..c721e6139f4cbe77b263fe0e626de71feea35997 100644 --- a/man/Load.Rd +++ b/man/Load.Rd @@ -1,161 +1,98 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Load.R \name{Load} \alias{Load} \title{Loads Experimental And Observational Data} -\description{ -This function loads monthly or daily data from a set of specified experimental datasets together with data that date-corresponds from a set of specified observational datasets. See parameters 'storefreq', 'sampleperiod', 'exp' and 'obs'.\cr\cr -A set of starting dates is specified through the parameter 'sdates'. Data of each starting date is loaded for each model. -\code{Load()} arranges the data in two arrays with a similar format both with the following dimensions: - \enumerate{ - \item{The number of experimental datasets determined by the user through the argument 'exp' (for the experimental data array) or the number of observational datasets available for validation (for the observational array) determined as well by the user through the argument 'obs'.} - \item{The greatest number of members across all experiments (in the experimental data array) or across all observational datasets (in the observational data array).} - \item{The number of starting dates determined by the user through the 'sdates' argument.} - \item{The greatest number of lead-times.} - \item{The number of latitudes of the selected zone.} - \item{The number of longitudes of the selected zone.} - } -Dimensions 5 and 6 are optional and their presence depends on the type of the specified variable (global mean or 2-dimensional) and on the selected output type (area averaged time series, latitude averaged time series, longitude averaged time series or 2-dimensional time series).\cr -In the case of loading an area average the dimensions of the arrays will be only the first 4.\cr\cr - -Only a specified variable is loaded from each experiment at each starting date. See parameter 'var'.\cr -Afterwards, observational data that matches every starting date and lead-time of every experimental dataset is fetched in the file system (so, if two predictions at two different start dates overlap, some observational values will be loaded and kept in memory more than once).\cr -If no data is found in the file system for an experimental or observational array point it is filled with an NA value.\cr\cr - -If the specified output is 2-dimensional or latitude- or longitude-averaged time series all the data is interpolated into a common grid. If the specified output type is area averaged time series the data is averaged on the individual grid of each dataset but can also be averaged after interpolating into a common grid. See parameters 'grid' and 'method'.\cr -Once the two arrays are filled by calling this function, other functions in the s2dverification package that receive as inputs data formatted in this data structure can be executed (e.g: \code{Clim()} to compute climatologies, \code{Ano()} to compute anomalies, ...).\cr\cr - -Load() has many additional parameters to disable values and trim dimensions of selected variable, even masks can be applied to 2-dimensional variables. See parameters 'nmember', 'nmemberobs', 'nleadtime', 'leadtimemin', 'leadtimemax', 'sampleperiod', 'lonmin', 'lonmax', 'latmin', 'latmax', 'maskmod', 'maskobs', 'varmin', 'varmax'.\cr\cr - -The parameters 'exp' and 'obs' can take various forms. The most direct form is a list of lists, where each sub-list has the component 'path' associated to a character string with a pattern of the path to the files of a dataset to be loaded. These patterns can contain wildcards and tags that will be replaced automatically by \code{Load()} with the specified starting dates, member numbers, variable name, etc.\cr -See parameter 'exp' or 'obs' for details.\cr\cr +\usage{ +Load(var, exp = NULL, obs = NULL, sdates, nmember = NULL, + nmemberobs = NULL, nleadtime = NULL, leadtimemin = 1, + leadtimemax = NULL, storefreq = "monthly", sampleperiod = 1, + lonmin = 0, lonmax = 360, latmin = -90, latmax = 90, + output = "areave", method = "conservative", grid = NULL, + maskmod = vector("list", 15), maskobs = vector("list", 15), + configfile = NULL, varmin = NULL, varmax = NULL, silent = FALSE, + nprocs = NULL, dimnames = NULL, remapcells = 2, + path_glob_permissive = "partial") +} +\arguments{ +\item{var}{Short name of the variable to load. It should coincide with the +variable name inside the data files.\cr +E.g.: \code{var = 'tos'}, \code{var = 'tas'}, \code{var = 'prlr'}.\cr +In some cases, though, the path to the files contains twice or more times +the short name of the variable but the actual name of the variable inside +the data files is different. In these cases it may be convenient to provide +\code{var} with the name that appears in the file paths (see details on +parameters \code{exp} and \code{obs}).} -Only NetCDF files are supported. OPeNDAP URLs to NetCDF files are also supported.\cr -\code{Load()} can load 2-dimensional or global mean variables in any of the following formats: +\item{exp}{Parameter to specify which experimental datasets to load data +from.\cr +It can take two formats: a list of lists or a vector of character strings. +Each format will trigger a different mechanism of locating the requested +datasets.\cr +The first format is adequate when loading data you'll only load once or +occasionally. The second format is targeted to avoid providing repeatedly +the information on a certain dataset but is more complex to use.\cr\cr +IMPORTANT: Place first the experiment with the largest number of members +and, if possible, with the largest number of leadtimes. If not possible, +the arguments 'nmember' and/or 'nleadtime' should be filled to not miss +any member or leadtime.\cr +If 'exp' is not specified or set to NULL, observational data is loaded for +each start-date as far as 'leadtimemax'. If 'leadtimemax' is not provided, +\code{Load()} will retrieve data of a period of time as long as the time +period between the first specified start date and the current date.\cr\cr +List of lists:\cr +A list of lists where each sub-list contains information on the location +and format of the data files of the dataset to load.\cr +Each sub-list can have the following components: \itemize{ - \item{experiments: - \itemize{ - \item{file per ensemble per starting date (YYYY, MM and DD somewhere in the path)} - \item{file per member per starting date (YYYY, MM, DD and MemberNumber somewhere in the path. Ensemble experiments with different numbers of members can be loaded in a single \code{Load()} call.)} - } -(YYYY, MM and DD specify the starting dates of the predictions) + \item{'name': A character string to identify the dataset. Optional.} + \item{'path': A character string with the pattern of the path to the + files of the dataset. This pattern can be built up making use of some + special tags that \code{Load()} will replace with the appropriate + values to find the dataset files. The allowed tags are $START_DATE$, + $YEAR$, $MONTH$, $DAY$, $MEMBER_NUMBER$, $STORE_FREQ$, $VAR_NAME$, + $EXP_NAME$ (only for experimental datasets), $OBS_NAME$ (only for + observational datasets) and $SUFFIX$\cr + Example: /path/to/$EXP_NAME$/postprocessed/$VAR_NAME$/\cr + $VAR_NAME$_$START_DATE$.nc\cr + If 'path' is not specified and 'name' is specified, the dataset + information will be fetched with the same mechanism as when using + the vector of character strings (read below). } - \item{observations: - \itemize{ - \item{file per ensemble per month (YYYY and MM somewhere in the path)} - \item{file per member per month (YYYY, MM and MemberNumber somewhere in the path, obs with different numbers of members supported)} - \item{file per dataset (No constraints in the path but the time axes in the file have to be properly defined)} - } -(YYYY and MM correspond to the actual month data in the file) + \item{'nc_var_name': Character string with the actual variable name + to look for inside the dataset files. Optional. Takes, by default, + the same value as the parameter 'var'. } - } -In all the formats the data can be stored in a daily or monthly frequency, or a multiple of these (see parameters 'storefreq' and 'sampleperiod').\cr -All the data files must contain the target variable defined over time and potentially over members, latitude and longitude dimensions in any order, time being the record dimension.\cr -In the case of a two-dimensional variable, the variables longitude and latitude must be defined inside the data file too and must have the same names as the dimension for longitudes and latitudes respectively.\cr -The names of these dimensions (and longitude and latitude variables) and the name for the members dimension are expected to be 'longitude', 'latitude' and 'ensemble' respectively. However, these names can be adjusted with the parameter 'dimnames' or can be configured in the configuration file (read below in parameters 'exp', 'obs' or see \code{?ConfigFileOpen} for more information.\cr -All the data files are expected to have numeric values representable with 32 bits. Be aware when choosing the fill values or infinite values in the datasets to load.\cr\cr - -The Load() function returns a named list following a structure similar to the used in the package 'downscaleR'.\cr -The components are the following: - \itemize{ - \item{'mod' is the array that contains the experimental data. It has the attribute 'dimensions' associated to a vector of strings with the labels of each dimension of the array, in order.} - \item{'obs' is the array that contains the observational data. It has the attribute 'dimensions' associated to a vector of strings with the labels of each dimension of the array, in order.} - \item{'obs' is the array that contains the observational data.} - \item{'lat' and 'lon' are the latitudes and longitudes of the grid into which the data is interpolated (0 if the loaded variable is a global mean or the output is an area average).\cr -Both have the attribute 'cdo_grid_des' associated with a character string with the name of the common grid of the data, following the CDO naming conventions for grids.\cr -The attribute 'projection' is kept for compatibility with 'downscaleR'.} - \item{'Variable' has the following components: - \itemize{ - \item{'varName', with the short name of the loaded variable as specified in the parameter 'var'.} - \item{'level', with information on the pressure level of the variable. Is kept to NULL by now.} - } -And the following attributes: - \itemize{ - \item{'is_standard', kept for compatibility with 'downscaleR', tells if a dataset has been homogenized to standards with 'downscaleR' catalogs.} - \item{'units', a character string with the units of measure of the variable, as found in the source files.} - \item{'longname', a character string with the long name of the variable, as found in the source files.} - \item{'daily_agg_cellfun', 'monthly_agg_cellfun', 'verification_time', kept for compatibility with 'downscaleR'.} - } + \item{'suffix': Wildcard character string that can be used to build + the 'path' of the dataset. It can be accessed with the tag $SUFFIX$. + Optional. Takes '' by default. } - \item{'Datasets' has the following components: - \itemize{ - \item{'exp', a named list where the names are the identifying character strings of each experiment in 'exp', each associated to a list with the following components: - \itemize{ - \item{'members', a list with the names of the members of the dataset.} - \item{'source', a path or URL to the source of the dataset.} - } - } - \item{'obs', similar to 'exp' but for observational datasets.} - } + \item{'var_min': Important: Character string. Minimum value beyond + which read values will be deactivated to NA. Optional. No deactivation + is performed by default. } - \item{'Dates', with the follwing components: - \itemize{ - \item{'start', an array of dimensions (sdate, time) with the POSIX initial date of each forecast time of each starting date.} - \item{'end', an array of dimensions (sdate, time) with the POSIX final date of each forecast time of each starting date.} - } + \item{'var_max': Important: Character string. Maximum value beyond + which read values will be deactivated to NA. Optional. No deactivation + is performed by default. } - \item{'InitializationDates', a vector of starting dates as specified in 'sdates', in POSIX format.} - \item{'when', a time stamp of the date the \code{Load()} call to obtain the data was issued.} - \item{'source_files', a vector of character strings with complete paths to all the found files involved in the \code{Load()} call.} - \item{'not_found_files', a vector of character strings with complete paths to not found files involved in the \code{Load()} call.} } -} -\usage{ -Load(var, exp = NULL, obs = NULL, sdates, nmember = NULL, - nmemberobs = NULL, nleadtime = NULL, leadtimemin = 1, - leadtimemax = NULL, storefreq = 'monthly', sampleperiod = 1, - lonmin = 0, lonmax = 360, latmin = -90, latmax = 90, - output = 'areave', method = 'conservative', grid = NULL, - maskmod = vector("list", 15), maskobs = vector("list", 15), - configfile = NULL, varmin = NULL, varmax = NULL, - silent = FALSE, nprocs = NULL, dimnames = NULL, - remapcells = 2, path_glob_permissive = 'partial') -} -\arguments{ - \item{var}{ -Short name of the variable to load. It should coincide with the variable name inside the data files.\cr -E.g.: \code{var = 'tos'}, \code{var = 'tas'}, \code{var = 'prlr'}.\cr -In some cases, though, the path to the files contains twice or more times the short name of the variable but the actual name of the variable inside the data files is different. In these cases it may be convenient to provide \code{var} with the name that appears in the file paths (see details on parameters \code{exp} and \code{obs}). - } - \item{exp}{ -Parameter to specify which experimental datasets to load data from.\cr -It can take two formats: a list of lists or a vector of character strings. Each format will trigger a different mechanism of locating the requested datasets.\cr -The first format is adequate when loading data you'll only load once or occasionally. The second format is targeted to avoid providing repeatedly the information on a certain dataset but is more complex to use.\cr\cr -IMPORTANT: Place first the experiment with the largest number of members and, if possible, with the largest number of leadtimes. If not possible, the arguments 'nmember' and/or 'nleadtime' should be filled to not miss any member or leadtime.\cr -If 'exp' is not specified or set to NULL, observational data is loaded for each start-date as far as 'leadtimemax'. If 'leadtimemax' is not provided, \code{Load()} will retrieve data of a period of time as long as the time period between the first specified start date and the current date.\cr -\cr -List of lists:\cr -A list of lists where each sub-list contains information on the location and format of the data files of the dataset to load.\cr -Each sub-list can have the following components: - \itemize{ - \item{ -'name': A character string to identify the dataset. Optional. - } - \item{ -'path': A character string with the pattern of the path to the files of the dataset. This pattern can be built up making use of some special tags that \code{Load()} will replace with the appropriate values to find the dataset files. The allowed tags are $START_DATE$, $YEAR$, $MONTH$, $DAY$, $MEMBER_NUMBER$, $STORE_FREQ$, $VAR_NAME$, $EXP_NAME$ (only for experimental datasets), $OBS_NAME$ (only for observational datasets) and $SUFFIX$\cr -Example: /path/to/$EXP_NAME$/postprocessed/$VAR_NAME$/\cr - $VAR_NAME$_$START_DATE$.nc\cr -If 'path' is not specified and 'name' is specified, the dataset information will be fetched with the same mechanism as when using the vector of character strings (read below). - } - \item{ -'nc_var_name': Character string with the actual variable name to look for inside the dataset files. Optional. Takes, by default, the same value as the parameter 'var'. - } - \item{ -'suffix': Wildcard character string that can be used to build the 'path' of the dataset. It can be accessed with the tag $SUFFIX$. Optional. Takes '' by default. - } - \item{ -'var_min': Important: Character string. Minimum value beyond which read values will be deactivated to NA. Optional. No deactivation is performed by default. - } - \item{ -'var_max': Important: Character string. Maximum value beyond which read values will be deactivated to NA. Optional. No deactivation is performed by default. - } - } -The tag $START_DATES$ will be replaced with all the starting dates specified in 'sdates'. $YEAR$, $MONTH$ and $DAY$ will take a value for each iteration over 'sdates', simply these are the same as $START_DATE$ but split in parts.\cr -$MEMBER_NUMBER$ will be replaced by a character string with each member number, from 1 to the value specified in the parameter 'nmember' (in experimental datasets) or in 'nmemberobs' (in observational datasets). It will range from '01' to 'N' or '0N' if N < 10.\cr -$STORE_FREQ$ will take the value specified in the parameter 'storefreq' ('monthly' or 'daily').\cr +The tag $START_DATES$ will be replaced with all the starting dates +specified in 'sdates'. $YEAR$, $MONTH$ and $DAY$ will take a value for each +iteration over 'sdates', simply these are the same as $START_DATE$ but +split in parts.\cr +$MEMBER_NUMBER$ will be replaced by a character string with each member +number, from 1 to the value specified in the parameter 'nmember' (in +experimental datasets) or in 'nmemberobs' (in observational datasets). It +will range from '01' to 'N' or '0N' if N < 10.\cr +$STORE_FREQ$ will take the value specified in the parameter 'storefreq' +('monthly' or 'daily').\cr $VAR_NAME$ will take the value specified in the parameter 'var'.\cr -$EXP_NAME$ will take the value specified in each component of the parameter 'exp' in the sub-component 'name'.\cr -$OBS_NAME$ will take the value specified in each component of the parameter 'obs' in the sub-component 'obs.\cr -$SUFFIX$ will take the value specified in each component of the parameters 'exp' and 'obs' in the sub-component 'suffix'.\cr - +$EXP_NAME$ will take the value specified in each component of the parameter +'exp' in the sub-component 'name'.\cr +$OBS_NAME$ will take the value specified in each component of the parameter +'obs' in the sub-component 'obs.\cr +$SUFFIX$ will take the value specified in each component of the parameters +'exp' and 'obs' in the sub-component 'suffix'.\cr Example: \preformatted{ list( @@ -171,255 +108,609 @@ list( ) ) } -This will make \code{Load()} look for, for instance, the following paths, if 'sdates' is c('19901101', '19951101', '20001101'):\cr +This will make \code{Load()} look for, for instance, the following paths, +if 'sdates' is c('19901101', '19951101', '20001101'):\cr /path/to/experimentA/monthly_mean/tas_3hourly/tas_19901101.nc\cr /path/to/experimentA/monthly_mean/tas_3hourly/tas_19951101.nc\cr /path/to/experimentA/monthly_mean/tas_3hourly/tas_20001101.nc\cr\cr - Vector of character strings: -To avoid specifying constantly the same information to load the same datasets, a vector with only the names of the datasets to load can be specified.\cr -\code{Load()} will then look for the information in a configuration file whose path must be specified in the parameter 'configfile'.\cr -Check \code{?ConfigFileCreate}, \code{ConfigFileOpen}, \code{ConfigEditEntry} & co. to learn how to create a new configuration file and how to add the information there. +To avoid specifying constantly the same information to load the same +datasets, a vector with only the names of the datasets to load can be +specified.\cr +\code{Load()} will then look for the information in a configuration file +whose path must be specified in the parameter 'configfile'.\cr +Check \code{?ConfigFileCreate}, \code{ConfigFileOpen}, +\code{ConfigEditEntry} & co. to learn how to create a new configuration +file and how to add the information there.\cr +Example: c('experimentA', 'experimentB')} -Example: c('experimentA', 'experimentB') - } - \item{obs}{ -Argument with the same format as parameter 'exp'. See details on parameter 'exp'.\cr -If 'obs' is not specified or set to NULL, no observational data is loaded.\cr - } - \item{sdates}{ -Vector of starting dates of the experimental runs to be loaded following the pattern 'YYYYMMDD'.\cr +\item{obs}{Argument with the same format as parameter 'exp'. See details on +parameter 'exp'.\cr +If 'obs' is not specified or set to NULL, no observational data is loaded.\cr} + +\item{sdates}{Vector of starting dates of the experimental runs to be loaded +following the pattern 'YYYYMMDD'.\cr This argument is mandatory.\cr -Ex: c('19601101', '19651101', '19701101') - } - \item{nmember}{ -Vector with the numbers of members to load from the specified experimental datasets in 'exp'.\cr -If not specified, the automatically detected number of members of the first experimental dataset is detected and replied to all the experimental datasets.\cr -If a single value is specified it is replied to all the experimental datasets.\cr -Data for each member is fetched in the file system. If not found is filled with NA values.\cr -An NA value in the 'nmember' list is interpreted as "fetch as many members of each experimental dataset as the number of members of the first experimental dataset".\cr -Note: It is recommended to specify the number of members of the first experimental dataset if it is stored in file per member format because there are known issues in the automatic detection of members if the path to the dataset in the configuration file contains Shell Globbing wildcards such as '*'.\cr -Ex: c(4, 9) - } - \item{nmemberobs}{ -Vector with the numbers of members to load from the specified observational datasets in 'obs'.\cr -If not specified, the automatically detected number of members of the first observational dataset is detected and replied to all the observational datasets.\cr -If a single value is specified it is replied to all the observational datasets.\cr -Data for each member is fetched in the file system. If not found is filled with NA values.\cr -An NA value in the 'nmemberobs' list is interpreted as "fetch as many members of each observational dataset as the number of members of the first observational dataset".\cr -Note: It is recommended to specify the number of members of the first observational dataset if it is stored in file per member format because there are known issues in the automatic detection of members if the path to the dataset in the configuration file contains Shell Globbing wildcards such as '*'.\cr -Ex: c(1, 5) - } - \item{nleadtime}{ -Deprecated. See parameter 'leadtimemax'.\cr - } - \item{leadtimemin}{ -Only lead-times higher or equal to 'leadtimemin' are loaded. Takes by default value 1. - } - \item{leadtimemax}{ -Only lead-times lower or equal to 'leadtimemax' are loaded. Takes by default the number of lead-times of the first experimental dataset in 'exp'.\cr -If 'exp' is NULL this argument won't have any effect (see \code{?Load} description). - } - \item{storefreq}{ -Frequency at which the data to be loaded is stored in the file system. Can take values 'monthly' or 'daily'.\cr +E.g. c('19601101', '19651101', '19701101')} + +\item{nmember}{Vector with the numbers of members to load from the specified +experimental datasets in 'exp'.\cr +If not specified, the automatically detected number of members of the +first experimental dataset is detected and replied to all the experimental +datasets.\cr +If a single value is specified it is replied to all the experimental +datasets.\cr +Data for each member is fetched in the file system. If not found is +filled with NA values.\cr +An NA value in the 'nmember' list is interpreted as "fetch as many members +of each experimental dataset as the number of members of the first +experimental dataset".\cr +Note: It is recommended to specify the number of members of the first +experimental dataset if it is stored in file per member format because +there are known issues in the automatic detection of members if the path +to the dataset in the configuration file contains Shell Globbing wildcards +such as '*'.\cr +E.g., c(4, 9)} + +\item{nmemberobs}{Vector with the numbers of members to load from the +specified observational datasets in 'obs'.\cr +If not specified, the automatically detected number of members of the +first observational dataset is detected and replied to all the +observational datasets.\cr +If a single value is specified it is replied to all the observational +datasets.\cr +Data for each member is fetched in the file system. If not found is +filled with NA values.\cr +An NA value in the 'nmemberobs' list is interpreted as "fetch as many +members of each observational dataset as the number of members of the +first observational dataset".\cr +Note: It is recommended to specify the number of members of the first +observational dataset if it is stored in file per member format because +there are known issues in the automatic detection of members if the path +to the dataset in the configuration file contains Shell Globbing wildcards +such as '*'.\cr +E.g., c(1, 5)} + +\item{nleadtime}{Deprecated. See parameter 'leadtimemax'.} + +\item{leadtimemin}{Only lead-times higher or equal to 'leadtimemin' are +loaded. Takes by default value 1.} + +\item{leadtimemax}{Only lead-times lower or equal to 'leadtimemax' are loaded. +Takes by default the number of lead-times of the first experimental +dataset in 'exp'.\cr +If 'exp' is NULL this argument won't have any effect +(see \code{?Load} description).} + +\item{storefreq}{Frequency at which the data to be loaded is stored in the +file system. Can take values 'monthly' or 'daily'.\cr By default it takes 'monthly'.\cr -Note: Data stored in other frequencies with a period which is divisible by a month can be loaded with a proper use of 'storefreq' and 'sampleperiod' parameters. It can also be loaded if the period is divisible by a day and the observational datasets are stored in a file per dataset format or 'obs' is empty. - } - \item{sampleperiod}{ -To load only a subset between 'leadtimemin' and 'leadtimemax' with the period of subsampling 'sampleperiod'.\cr +Note: Data stored in other frequencies with a period which is divisible by +a month can be loaded with a proper use of 'storefreq' and 'sampleperiod' +parameters. It can also be loaded if the period is divisible by a day and +the observational datasets are stored in a file per dataset format or +'obs' is empty.} + +\item{sampleperiod}{To load only a subset between 'leadtimemin' and +'leadtimemax' with the period of subsampling 'sampleperiod'.\cr Takes by default value 1 (all lead-times are loaded).\cr -See 'storefreq' for more information. - } - \item{lonmin}{ -If a 2-dimensional variable is loaded, values at longitudes lower than 'lonmin' aren't loaded.\cr -Must take a value in the range [-360, 360] (if negative longitudes are found in the data files these are translated to this range).\cr +See 'storefreq' for more information.} + +\item{lonmin}{If a 2-dimensional variable is loaded, values at longitudes +lower than 'lonmin' aren't loaded.\cr +Must take a value in the range [-360, 360] (if negative longitudes are +found in the data files these are translated to this range).\cr It is set to 0 if not specified.\cr -If 'lonmin' > 'lonmax', data across Greenwich is loaded. - } - \item{lonmax}{ -If a 2-dimensional variable is loaded, values at longitudes higher than 'lonmax' aren't loaded.\cr -Must take a value in the range [-360, 360] (if negative longitudes are found in the data files these are translated to this range).\cr +If 'lonmin' > 'lonmax', data across Greenwich is loaded.} + +\item{lonmax}{If a 2-dimensional variable is loaded, values at longitudes +higher than 'lonmax' aren't loaded.\cr +Must take a value in the range [-360, 360] (if negative longitudes are +found in the data files these are translated to this range).\cr It is set to 360 if not specified.\cr -If 'lonmin' > 'lonmax', data across Greenwich is loaded. - } - \item{latmin}{ -If a 2-dimensional variable is loaded, values at latitudes lower than 'latmin' aren't loaded.\cr +If 'lonmin' > 'lonmax', data across Greenwich is loaded.} + +\item{latmin}{If a 2-dimensional variable is loaded, values at latitudes +lower than 'latmin' aren't loaded.\cr Must take a value in the range [-90, 90].\cr -It is set to -90 if not specified. - } - \item{latmax}{ -If a 2-dimensional variable is loaded, values at latitudes higher than 'latmax' aren't loaded.\cr +It is set to -90 if not specified.} + +\item{latmax}{If a 2-dimensional variable is loaded, values at latitudes +higher than 'latmax' aren't loaded.\cr Must take a value in the range [-90, 90].\cr -It is set to 90 if not specified. - } - \item{output}{ -This parameter determines the format in which the data is arranged in the output arrays.\cr +It is set to 90 if not specified.} + +\item{output}{This parameter determines the format in which the data is +arranged in the output arrays.\cr Can take values 'areave', 'lon', 'lat', 'lonlat'.\cr - \itemize{ - \item{'areave': Time series of area-averaged variables over the specified domain.} - \item{'lon': Time series of meridional averages as a function of longitudes.} - \item{'lat': Time series of zonal averages as a function of latitudes.} - \item{'lonlat': Time series of 2d fields.} - } -Takes by default the value 'areave'. If the variable specified in 'var' is a global mean, this parameter is forced to 'areave'.\cr -All the loaded data is interpolated into the grid of the first experimental dataset except if 'areave' is selected. In that case the area averages are computed on each dataset original grid. A common grid different than the first experiment's can be specified through the parameter 'grid'. If 'grid' is specified when selecting 'areave' output type, all the loaded data is interpolated into the specified grid before calculating the area averages. - } - \item{method}{ -This parameter determines the interpolation method to be used when regridding data (see 'output'). Can take values 'bilinear', 'bicubic', 'conservative', 'distance-weighted'.\cr + \itemize{ + \item{'areave': Time series of area-averaged variables over the specified domain.} + \item{'lon': Time series of meridional averages as a function of longitudes.} + \item{'lat': Time series of zonal averages as a function of latitudes.} + \item{'lonlat': Time series of 2d fields.} +} +Takes by default the value 'areave'. If the variable specified in 'var' is +a global mean, this parameter is forced to 'areave'.\cr +All the loaded data is interpolated into the grid of the first experimental +dataset except if 'areave' is selected. In that case the area averages are +computed on each dataset original grid. A common grid different than the +first experiment's can be specified through the parameter 'grid'. If 'grid' +is specified when selecting 'areave' output type, all the loaded data is +interpolated into the specified grid before calculating the area averages.} + +\item{method}{This parameter determines the interpolation method to be used +when regridding data (see 'output'). Can take values 'bilinear', 'bicubic', +'conservative', 'distance-weighted'.\cr See \code{remapcells} for advanced adjustments.\cr -Takes by default the value 'conservative'. - } - \item{grid}{ -A common grid can be specified through the parameter 'grid' when loading 2-dimensional data. Data is then interpolated onto this grid whichever 'output' type is specified. If the selected output type is 'areave' and a 'grid' is specified, the area averages are calculated after interpolating to the specified grid.\cr -If not specified and the selected output type is 'lon', 'lat' or 'lonlat', this parameter takes as default value the grid of the first experimental dataset, which is read automatically from the source files.\cr -The grid must be supported by 'cdo' tools. Now only supported: rNXxNY or tTRgrid.\cr -Both rNXxNY and tRESgrid yield rectangular regular grids. rNXxNY yields grids that are evenly spaced in longitudes and latitudes (in degrees). tRESgrid refers to a grid generated with series of spherical harmonics truncated at the RESth harmonic. However these spectral grids are usually associated to a gaussian grid, the latitudes of which are spaced with a Gaussian quadrature (not evenly spaced in degrees). The pattern tRESgrid will yield a gaussian grid.\cr -Ex: 'r96x72' -Advanced: If the output type is 'lon', 'lat' or 'lonlat' and no common grid is specified, the grid of the first experimental or observational dataset is detected and all data is then interpolated onto this grid. If the first experimental or observational dataset's data is found shifted along the longitudes (i.e., there's no value at the longitude 0 but at a longitude close to it), the data is re-interpolated to suppress the shift. This has to be done in order to make sure all the data from all the datasets is properly aligned along longitudes, as there's no option so far in \code{Load} to specify grids starting at longitudes other than 0. This issue doesn't affect when loading in 'areave' mode without a common grid, the data is not re-interpolated in that case. - } - \item{maskmod}{ -List of masks to be applied to the data of each experimental dataset respectively, if a 2-dimensional variable is specified in 'var'.\cr +Takes by default the value 'conservative'.} + +\item{grid}{A common grid can be specified through the parameter 'grid' when +loading 2-dimensional data. Data is then interpolated onto this grid +whichever 'output' type is specified. If the selected output type is +'areave' and a 'grid' is specified, the area averages are calculated after +interpolating to the specified grid.\cr +If not specified and the selected output type is 'lon', 'lat' or 'lonlat', +this parameter takes as default value the grid of the first experimental +dataset, which is read automatically from the source files.\cr +The grid must be supported by 'cdo' tools. Now only supported: rNXxNY +or tTRgrid.\cr +Both rNXxNY and tRESgrid yield rectangular regular grids. rNXxNY yields +grids that are evenly spaced in longitudes and latitudes (in degrees). +tRESgrid refers to a grid generated with series of spherical harmonics +truncated at the RESth harmonic. However these spectral grids are usually +associated to a gaussian grid, the latitudes of which are spaced with a +Gaussian quadrature (not evenly spaced in degrees). The pattern tRESgrid +will yield a gaussian grid.\cr +E.g., 'r96x72' +Advanced: If the output type is 'lon', 'lat' or 'lonlat' and no common +grid is specified, the grid of the first experimental or observational +dataset is detected and all data is then interpolated onto this grid. +If the first experimental or observational dataset's data is found shifted +along the longitudes (i.e., there's no value at the longitude 0 but at a +longitude close to it), the data is re-interpolated to suppress the shift. +This has to be done in order to make sure all the data from all the +datasets is properly aligned along longitudes, as there's no option so far +in \code{Load} to specify grids starting at longitudes other than 0. +This issue doesn't affect when loading in 'areave' mode without a common +grid, the data is not re-interpolated in that case.} + +\item{maskmod}{List of masks to be applied to the data of each experimental +dataset respectively, if a 2-dimensional variable is specified in 'var'.\cr Each mask can be defined in 2 formats:\cr a) a matrix with dimensions c(longitudes, latitudes).\cr b) a list with the components 'path' and, optionally, 'nc_var_name'.\cr -In the format a), the matrix must have the same size as the common grid or with the same size as the grid of the corresponding experimental dataset if 'areave' output type is specified and no common 'grid' is specified.\cr -In the format b), the component 'path' must be a character string with the path to a NetCDF mask file, also in the common grid or in the grid of the corresponding dataset if 'areave' output type is specified and no common 'grid' is specified. If the mask file contains only a single variable, there's no need to specify the component 'nc_var_name'. Otherwise it must be a character string with the name of the variable inside the mask file that contains the mask values. This variable must be defined only over 2 dimensions with length greater or equal to 1.\cr -Whichever the mask format, a value of 1 at a point of the mask keeps the original value at that point whereas a value of 0 disables it (replaces by a NA value).\cr +In the format a), the matrix must have the same size as the common grid +or with the same size as the grid of the corresponding experimental dataset +if 'areave' output type is specified and no common 'grid' is specified.\cr +In the format b), the component 'path' must be a character string with the +path to a NetCDF mask file, also in the common grid or in the grid of the +corresponding dataset if 'areave' output type is specified and no common +'grid' is specified. If the mask file contains only a single variable, +there's no need to specify the component 'nc_var_name'. Otherwise it must +be a character string with the name of the variable inside the mask file +that contains the mask values. This variable must be defined only over 2 +dimensions with length greater or equal to 1.\cr +Whichever the mask format, a value of 1 at a point of the mask keeps the +original value at that point whereas a value of 0 disables it (replaces +by a NA value).\cr By default all values are kept (all ones).\cr -The longitudes and latitudes in the matrix must be in the same order as in the common grid or as in the original grid of the corresponding dataset when loading in 'areave' mode. You can find out the order of the longitudes and latitudes of a file with 'cdo griddes'.\cr -Note that in a common CDO grid defined with the patterns 'tgrid' or 'rx' the latitudes and latitudes are ordered, by definition, from -90 to 90 and from 0 to 360, respectively.\cr -If you are loading maps ('lonlat', 'lon' or 'lat' output types) all the data will be interpolated onto the common 'grid'. If you want to specify a mask, you will have to provide it already interpolated onto the common grid (you may use 'cdo' libraries for this purpose). It is not usual to apply different masks on experimental datasets on the same grid, so all the experiment masks are expected to be the same.\cr -Warning: When loading maps, any masks defined for the observational data will be ignored to make sure the same mask is applied to the experimental and observational data.\cr +The longitudes and latitudes in the matrix must be in the same order as in +the common grid or as in the original grid of the corresponding dataset +when loading in 'areave' mode. You can find out the order of the longitudes +and latitudes of a file with 'cdo griddes'.\cr +Note that in a common CDO grid defined with the patterns 'tgrid' or +'rx' the latitudes and latitudes are ordered, by definition, from +-90 to 90 and from 0 to 360, respectively.\cr +If you are loading maps ('lonlat', 'lon' or 'lat' output types) all the +data will be interpolated onto the common 'grid'. If you want to specify +a mask, you will have to provide it already interpolated onto the common +grid (you may use 'cdo' libraries for this purpose). It is not usual to +apply different masks on experimental datasets on the same grid, so all +the experiment masks are expected to be the same.\cr +Warning: When loading maps, any masks defined for the observational data +will be ignored to make sure the same mask is applied to the experimental +and observational data.\cr Warning: list() compulsory even if loading 1 experimental dataset only!\cr -Ex: list(array(1, dim = c(num_lons, num_lats))) - } - \item{maskobs}{ -See help on parameter 'maskmod'. - } - \item{configfile}{ -Path to the s2dverification configuration file from which to retrieve information on location in file system (and other) of datasets.\cr -If not specified, the configuration file used at BSC-ES will be used (it is included in the package).\cr -Check the BSC's configuration file or a template of configuration file in the folder 'inst/config' in the package.\cr -Check further information on the configuration file mechanism in \code{ConfigFileOpen()}. - } - \item{varmin}{ -Loaded experimental and observational data values smaller than 'varmin' will be disabled (replaced by NA values).\cr -By default no deactivation is performed. - } - \item{varmax}{ -Loaded experimental and observational data values greater than 'varmax' will be disabled (replaced by NA values).\cr -By default no deactivation is performed. - } - \item{silent}{ -Parameter to show (FALSE) or hide (TRUE) information messages.\cr +E.g., list(array(1, dim = c(num_lons, num_lats)))} + +\item{maskobs}{See help on parameter 'maskmod'.} + +\item{configfile}{Path to the s2dverification configuration file from which +to retrieve information on location in file system (and other) of datasets.\cr +If not specified, the configuration file used at BSC-ES will be used +(it is included in the package).\cr +Check the BSC's configuration file or a template of configuration file in +the folder 'inst/config' in the package.\cr +Check further information on the configuration file mechanism in +\code{ConfigFileOpen()}.} + +\item{varmin}{Loaded experimental and observational data values smaller +than 'varmin' will be disabled (replaced by NA values).\cr +By default no deactivation is performed.} + +\item{varmax}{Loaded experimental and observational data values greater +than 'varmax' will be disabled (replaced by NA values).\cr +By default no deactivation is performed.} + +\item{silent}{Parameter to show (FALSE) or hide (TRUE) information messages.\cr Warnings will be displayed even if 'silent' is set to TRUE.\cr -Takes by default the value 'FALSE'. - } - \item{nprocs}{ -Number of parallel processes created to perform the fetch and computation of data.\cr -These processes will use shared memory in the processor in which Load() is launched.\cr -By default the number of logical cores in the machine will be detected and as many processes as logical cores there are will be created.\cr +Takes by default the value 'FALSE'.} + +\item{nprocs}{Number of parallel processes created to perform the fetch +and computation of data.\cr +These processes will use shared memory in the processor in which Load() +is launched.\cr +By default the number of logical cores in the machine will be detected +and as many processes as logical cores there are will be created.\cr A value of 1 won't create parallel processes.\cr -When running in multiple processes, if an error occurs in any of the processes, a crash message appears in the R session of the original process but no detail is given about the error. A value of 1 will display all error messages in the original and only R session.\cr -Note: the parallel process create other blocking processes each time they need to compute an interpolation via 'cdo'. - } - \item{dimnames}{ -Named list where the name of each element is a generic name of the expected dimensions inside the NetCDF files. These generic names are 'lon', 'lat' and 'member'. 'time' is not needed because it's detected automatically by discard.\cr -The value associated to each name is the actual dimension name in the NetCDF file.\cr -The variables in the file that contain the longitudes and latitudes of the data (if the data is a 2-dimensional variable) must have the same name as the longitude and latitude dimensions.\cr -By default, these names are 'longitude', 'latitude' and 'ensemble. If any of those is defined in the 'dimnames' parameter, it takes priority and overwrites the default value. -Ex.: list(lon = 'x', lat = 'y') -In that example, the dimension 'member' will take the default value 'ensemble'. - } - \item{remapcells}{ -When loading a 2-dimensional variable, spatial subsets can be requested via \code{lonmin}, \code{lonmax}, \code{latmin} and \code{latmax}. When \code{Load()} obtains the subset it is then interpolated if needed with the method specified in \code{method}.\cr -The result of this interpolation can vary if the values surrounding the spatial subset are not present. To better control this process, the width in number of grid cells of the surrounding area to be taken into account can be specified with \code{remapcells}. A value of 0 will take into account no additional cells but will generate less traffic between the storage and the R processes that load data.\cr -A value beyond the limits in the data files will be automatically runcated to the actual limit.\cr -The default value is 2. - } - \item{path_glob_permissive}{ -In some cases, when specifying a path pattern (either in the parameters 'exp'/'obs' or in a configuration file) one can specify path patterns that contain shell globbing expressions. Too much freedom in putting globbing expressions in the path patterns can be dangerous and make \code{Load()} find a file in the file system for a start date for a dataset that really does not belong to that dataset. For example, if the file system contains two directories for two different experiments that share a part of their path and the path pattern contains globbing expressions: +When running in multiple processes, if an error occurs in any of the +processes, a crash message appears in the R session of the original +process but no detail is given about the error. A value of 1 will display +all error messages in the original and only R session.\cr +Note: the parallel process create other blocking processes each time they +need to compute an interpolation via 'cdo'.} + +\item{dimnames}{Named list where the name of each element is a generic +name of the expected dimensions inside the NetCDF files. These generic +names are 'lon', 'lat' and 'member'. 'time' is not needed because it's +detected automatically by discard.\cr +The value associated to each name is the actual dimension name in the +NetCDF file.\cr +The variables in the file that contain the longitudes and latitudes of +the data (if the data is a 2-dimensional variable) must have the same +name as the longitude and latitude dimensions.\cr +By default, these names are 'longitude', 'latitude' and 'ensemble. If any +of those is defined in the 'dimnames' parameter, it takes priority and +overwrites the default value. +E.g., list(lon = 'x', lat = 'y') +In that example, the dimension 'member' will take the default value 'ensemble'.} + +\item{remapcells}{When loading a 2-dimensional variable, spatial subsets can +be requested via \code{lonmin}, \code{lonmax}, \code{latmin} and +\code{latmax}. When \code{Load()} obtains the subset it is then +interpolated if needed with the method specified in \code{method}.\cr +The result of this interpolation can vary if the values surrounding the +spatial subset are not present. To better control this process, the width +in number of grid cells of the surrounding area to be taken into account +can be specified with \code{remapcells}. A value of 0 will take into +account no additional cells but will generate less traffic between the +storage and the R processes that load data.\cr +A value beyond the limits in the data files will be automatically runcated +to the actual limit.\cr +The default value is 2.} + +\item{path_glob_permissive}{In some cases, when specifying a path pattern +(either in the parameters 'exp'/'obs' or in a configuration file) one can +specify path patterns that contain shell globbing expressions. Too much +freedom in putting globbing expressions in the path patterns can be +dangerous and make \code{Load()} find a file in the file system for a +start date for a dataset that really does not belong to that dataset. +For example, if the file system contains two directories for two different +experiments that share a part of their path and the path pattern contains +globbing expressions: /experiments/model1/expA/monthly_mean/tos/tos_19901101.nc /experiments/model2/expA/monthly_mean/tos/tos_19951101.nc -And the path pattern is used as in the example right below to load data of only the experiment 'expA' of the model 'model1' for the starting dates '19901101' and '19951101', \code{Load()} will undesiredly yield data for both starting dates, even if in fact there is data only for the first one:\cr +And the path pattern is used as in the example right below to load data of +only the experiment 'expA' of the model 'model1' for the starting dates +'19901101' and '19951101', \code{Load()} will undesiredly yield data for +both starting dates, even if in fact there is data only for the +first one:\cr \code{ expA <- list(path = file.path('/experiments/*/expA/monthly_mean/$VAR_NAME$', '$VAR_NAME$_$START_DATE$.nc') data <- Load('tos', list(expA), NULL, c('19901101', '19951101')) } -To avoid these situations, the parameter \code{path_glob_permissive} is set by default to \code{'partial'}, which forces \code{Load()} to replace all the globbing expressions of a path pattern of a data set by fixed values taken from the path of the first found file for each data set, up to the folder right before the final files (globbing expressions in the file name will not be replaced, only those in the path to the file). Replacement of globbing expressions in the file name can also be triggered by setting \code{path_glob_permissive} to \code{FALSE} or \code{'no'}. If needed to keep all globbing expressions, \code{path_glob_permissive} can be set to \code{TRUE} or \code{'yes'}. - } -} -\details{ -The two output matrices have between 2 and 6 dimensions:\cr - \enumerate{ - \item{Number of experimental/observational datasets.} - \item{Number of members.} - \item{Number of startdates.} - \item{Number of leadtimes.} - \item{Number of latitudes (optional).} - \item{Number of longitudes (optional).} - } -but the two matrices have the same number of dimensions and only the first two dimensions can have different lengths depending on the input arguments. - -For a detailed explanation of the process, read the documentation attached to the package or check the comments in the code. +To avoid these situations, the parameter \code{path_glob_permissive} is +set by default to \code{'partial'}, which forces \code{Load()} to replace +all the globbing expressions of a path pattern of a data set by fixed +values taken from the path of the first found file for each data set, up +to the folder right before the final files (globbing expressions in the +file name will not be replaced, only those in the path to the file). +Replacement of globbing expressions in the file name can also be triggered +by setting \code{path_glob_permissive} to \code{FALSE} or \code{'no'}. If +needed to keep all globbing expressions, \code{path_glob_permissive} can +be set to \code{TRUE} or \code{'yes'}.} } \value{ -\code{Load()} returns a named list following a structure similar to the used in the package 'downscaleR'.\cr +\code{Load()} returns a named list following a structure similar to the +used in the package 'downscaleR'.\cr The components are the following: - \itemize{ - \item{ -'mod' is the array that contains the experimental data. It has the attribute 'dimensions' associated to a vector of strings with the labels of each dimension of the array, in order. The order of the latitudes is always forced to be from 90 to -90 whereas the order of the longitudes is kept as in the original files (if possible). The longitude values provided in \code{lon} lower than 0 are added 360 (but still kept in the original order). In some cases, however, if multiple data sets are loaded in longitude-latitude mode, the longitudes (and also the data arrays in \code{mod} and \code{obs}) are re-ordered afterwards by \code{Load()} to range from 0 to 360; a warning is given in such cases. The longitude and latitude of the center of the grid cell that corresponds to the value [j, i] in 'mod' (along the dimensions latitude and longitude, respectively) can be found in the outputs \code{lon}[i] and \code{lat}[j] - } - \item{'obs' is the array that contains the observational data. The same documentation of parameter 'mod' applies to this parameter.} - \item{'lat' and 'lon' are the latitudes and longitudes of the centers of the cells of the grid the data is interpolated into (0 if the loaded variable is a global mean or the output is an area average).\cr -Both have the attribute 'cdo_grid_des' associated with a character string with the name of the common grid of the data, following the CDO naming conventions for grids.\cr -'lon' has the attributes 'first_lon' and 'last_lon', with the first and last longitude values found in the region defined by 'lonmin' and 'lonmax'. 'lat' has also the equivalent attributes 'first_lat' and 'last_lat'.\cr -'lon' has also the attribute 'data_across_gw' which tells whether the requested region via 'lonmin', 'lonmax', 'latmin', 'latmax' goes across the Greenwich meridian. As explained in the documentation of the parameter 'mod', the loaded data array is kept in the same order as in the original files when possible: this means that, in some cases, even if the data goes across the Greenwich, the data array may not go across the Greenwich. The attribute 'array_across_gw' tells whether the array actually goes across the Greenwich. E.g: The longitudes in the data files are defined to be from 0 to 360. The requested longitudes are from -80 to 40. The original order is kept, hence the longitudes in the array will be ordered as follows: 0, ..., 40, 280, ..., 360. In that case, 'data_across_gw' will be TRUE and 'array_across_gw' will be FALSE.\cr -The attribute 'projection' is kept for compatibility with 'downscaleR'.} - \item{'Variable' has the following components: - \itemize{ - \item{'varName', with the short name of the loaded variable as specified in the parameter 'var'.} - \item{'level', with information on the pressure level of the variable. Is kept to NULL by now.} - } -And the following attributes: - \itemize{ - \item{'is_standard', kept for compatibility with 'downscaleR', tells if a dataset has been homogenized to standards with 'downscaleR' catalogs.} - \item{'units', a character string with the units of measure of the variable, as found in the source files.} - \item{'longname', a character string with the long name of the variable, as found in the source files.} - \item{'daily_agg_cellfun', 'monthly_agg_cellfun', 'verification_time', kept for compatibility with 'downscaleR'.} - } - } - \item{'Datasets' has the following components: - \itemize{ - \item{'exp', a named list where the names are the identifying character strings of each experiment in 'exp', each associated to a list with the following components: - \itemize{ - \item{'members', a list with the names of the members of the dataset.} - \item{'source', a path or URL to the source of the dataset.} - } - } - \item{'obs', similar to 'exp' but for observational datasets.} - } - } - \item{'Dates', with the follwing components: - \itemize{ - \item{'start', an array of dimensions (sdate, time) with the POSIX initial date of each forecast time of each starting date.} - \item{'end', an array of dimensions (sdate, time) with the POSIX final date of each forecast time of each starting date.} - } - } - \item{'InitializationDates', a vector of starting dates as specified in 'sdates', in POSIX format.} - \item{'when', a time stamp of the date the \code{Load()} call to obtain the data was issued.} - \item{'source_files', a vector of character strings with complete paths to all the found files involved in the \code{Load()} call.} - \item{'not_found_files', a vector of character strings with complete paths to not found files involved in the \code{Load()} call.} - } + \itemize{ + \item{ + 'mod' is the array that contains the experimental data. It has the + attribute 'dimensions' associated to a vector of strings with the + labels of each dimension of the array, in order. The order of the + latitudes is always forced to be from 90 to -90 whereas the order of + the longitudes is kept as in the original files (if possible). The + longitude values provided in \code{lon} lower than 0 are added 360 + (but still kept in the original order). In some cases, however, if + multiple data sets are loaded in longitude-latitude mode, the + longitudes (and also the data arrays in \code{mod} and \code{obs}) are + re-ordered afterwards by \code{Load()} to range from 0 to 360; a + warning is given in such cases. The longitude and latitude of the + center of the grid cell that corresponds to the value [j, i] in 'mod' + (along the dimensions latitude and longitude, respectively) can be + found in the outputs \code{lon}[i] and \code{lat}[j] + } + \item{'obs' is the array that contains the observational data. The + same documentation of parameter 'mod' applies to this parameter.} + \item{'lat' and 'lon' are the latitudes and longitudes of the centers of + the cells of the grid the data is interpolated into (0 if the loaded + variable is a global mean or the output is an area average).\cr + Both have the attribute 'cdo_grid_des' associated with a character + string with the name of the common grid of the data, following the CDO + naming conventions for grids.\cr + 'lon' has the attributes 'first_lon' and 'last_lon', with the first + and last longitude values found in the region defined by 'lonmin' and + 'lonmax'. 'lat' has also the equivalent attributes 'first_lat' and + 'last_lat'.\cr + 'lon' has also the attribute 'data_across_gw' which tells whether the + requested region via 'lonmin', 'lonmax', 'latmin', 'latmax' goes across + the Greenwich meridian. As explained in the documentation of the + parameter 'mod', the loaded data array is kept in the same order as in + the original files when possible: this means that, in some cases, even + if the data goes across the Greenwich, the data array may not go + across the Greenwich. The attribute 'array_across_gw' tells whether + the array actually goes across the Greenwich. E.g: The longitudes in + the data files are defined to be from 0 to 360. The requested + longitudes are from -80 to 40. The original order is kept, hence the + longitudes in the array will be ordered as follows: + 0, ..., 40, 280, ..., 360. In that case, 'data_across_gw' will be TRUE + and 'array_across_gw' will be FALSE.\cr + The attribute 'projection' is kept for compatibility with 'downscaleR'. + } + \item{'Variable' has the following components: + \itemize{ + \item{'varName', with the short name of the loaded variable as + specified in the parameter 'var'. + } + \item{'level', with information on the pressure level of the + variable. Is kept to NULL by now. + } + } + And the following attributes: + \itemize{ + \item{'is_standard', kept for compatibility with 'downscaleR', + tells if a dataset has been homogenized to standards with + 'downscaleR' catalogs. + } + \item{'units', a character string with the units of measure of the + variable, as found in the source files. + } + \item{'longname', a character string with the long name of the + variable, as found in the source files. + } + \item{'daily_agg_cellfun', 'monthly_agg_cellfun', + 'verification_time', kept for compatibility with 'downscaleR'. + } + } + } + \item{'Datasets' has the following components: + \itemize{ + \item{'exp', a named list where the names are the identifying + character strings of each experiment in 'exp', each associated to + a list with the following components: + \itemize{ + \item{'members', a list with the names of the members of the dataset.} + \item{'source', a path or URL to the source of the dataset.} + } + } + \item{'obs', similar to 'exp' but for observational datasets.} + } + } + \item{'Dates', with the follwing components: + \itemize{ + \item{'start', an array of dimensions (sdate, time) with the POSIX + initial date of each forecast time of each starting date. + } + \item{'end', an array of dimensions (sdate, time) with the POSIX + final date of each forecast time of each starting date. + } + } + } + \item{'InitializationDates', a vector of starting dates as specified in + 'sdates', in POSIX format. + } + \item{'when', a time stamp of the date the \code{Load()} call to obtain + the data was issued. + } + \item{'source_files', a vector of character strings with complete paths + to all the found files involved in the \code{Load()} call. + } + \item{'not_found_files', a vector of character strings with complete + paths to not found files involved in the \code{Load()} call. + } + } } -\author{ -History:\cr -0.1 - 2011-03 (V. Guemas, \email{virginie.guemas at bsc.es}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Formatting to CRAN\cr -1.2 - 2015-02 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Generalisation + parallelisation\cr -1.3 - 2015-07 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Improvements related to configuration file mechanism\cr -1.4 - 2016-01 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Added subsetting capabilities\cr +\description{ +This function loads monthly or daily data from a set of specified +experimental datasets together with data that date-corresponds from a set +of specified observational datasets. See parameters 'storefreq', +'sampleperiod', 'exp' and 'obs'.\cr\cr +A set of starting dates is specified through the parameter 'sdates'. Data of +each starting date is loaded for each model. +\code{Load()} arranges the data in two arrays with a similar format both +with the following dimensions: + \enumerate{ + \item{The number of experimental datasets determined by the user through + the argument 'exp' (for the experimental data array) or the number of + observational datasets available for validation (for the observational + array) determined as well by the user through the argument 'obs'.} + \item{The greatest number of members across all experiments (in the + experimental data array) or across all observational datasets (in the + observational data array).} + \item{The number of starting dates determined by the user through the + 'sdates' argument.} + \item{The greatest number of lead-times.} + \item{The number of latitudes of the selected zone.} + \item{The number of longitudes of the selected zone.} + } +Dimensions 5 and 6 are optional and their presence depends on the type of +the specified variable (global mean or 2-dimensional) and on the selected +output type (area averaged time series, latitude averaged time series, +longitude averaged time series or 2-dimensional time series).\cr +In the case of loading an area average the dimensions of the arrays will be +only the first 4.\cr\cr +Only a specified variable is loaded from each experiment at each starting +date. See parameter 'var'.\cr +Afterwards, observational data that matches every starting date and lead-time +of every experimental dataset is fetched in the file system (so, if two +predictions at two different start dates overlap, some observational values +will be loaded and kept in memory more than once).\cr +If no data is found in the file system for an experimental or observational +array point it is filled with an NA value.\cr\cr +If the specified output is 2-dimensional or latitude- or longitude-averaged +time series all the data is interpolated into a common grid. If the +specified output type is area averaged time series the data is averaged on +the individual grid of each dataset but can also be averaged after +interpolating into a common grid. See parameters 'grid' and 'method'.\cr +Once the two arrays are filled by calling this function, other functions in +the s2dverification package that receive as inputs data formatted in this +data structure can be executed (e.g: \code{Clim()} to compute climatologies, +\code{Ano()} to compute anomalies, ...).\cr\cr +Load() has many additional parameters to disable values and trim dimensions +of selected variable, even masks can be applied to 2-dimensional variables. +See parameters 'nmember', 'nmemberobs', 'nleadtime', 'leadtimemin', +'leadtimemax', 'sampleperiod', 'lonmin', 'lonmax', 'latmin', 'latmax', +'maskmod', 'maskobs', 'varmin', 'varmax'.\cr\cr +The parameters 'exp' and 'obs' can take various forms. The most direct form +is a list of lists, where each sub-list has the component 'path' associated +to a character string with a pattern of the path to the files of a dataset +to be loaded. These patterns can contain wildcards and tags that will be +replaced automatically by \code{Load()} with the specified starting dates, +member numbers, variable name, etc.\cr +See parameter 'exp' or 'obs' for details.\cr\cr +Only NetCDF files are supported. OPeNDAP URLs to NetCDF files are also +supported.\cr +\code{Load()} can load 2-dimensional or global mean variables in any of the +following formats: + \itemize{ + \item{experiments: + \itemize{ + \item{file per ensemble per starting date + (YYYY, MM and DD somewhere in the path)} + \item{file per member per starting date + (YYYY, MM, DD and MemberNumber somewhere in the path. Ensemble + experiments with different numbers of members can be loaded in + a single \code{Load()} call.)} + } + (YYYY, MM and DD specify the starting dates of the predictions) + } + \item{observations: + \itemize{ + \item{file per ensemble per month + (YYYY and MM somewhere in the path)} + \item{file per member per month + (YYYY, MM and MemberNumber somewhere in the path, obs with different + numbers of members supported)} + \item{file per dataset (No constraints in the path but the time axes + in the file have to be properly defined)} + } + (YYYY and MM correspond to the actual month data in the file) + } + } +In all the formats the data can be stored in a daily or monthly frequency, +or a multiple of these (see parameters 'storefreq' and 'sampleperiod').\cr +All the data files must contain the target variable defined over time and +potentially over members, latitude and longitude dimensions in any order, +time being the record dimension.\cr +In the case of a two-dimensional variable, the variables longitude and +latitude must be defined inside the data file too and must have the same +names as the dimension for longitudes and latitudes respectively.\cr +The names of these dimensions (and longitude and latitude variables) and the +name for the members dimension are expected to be 'longitude', 'latitude' +and 'ensemble' respectively. However, these names can be adjusted with the +parameter 'dimnames' or can be configured in the configuration file (read +below in parameters 'exp', 'obs' or see \code{?ConfigFileOpen} +for more information.\cr +All the data files are expected to have numeric values representable with +32 bits. Be aware when choosing the fill values or infinite values in the +datasets to load.\cr\cr +The Load() function returns a named list following a structure similar to +the used in the package 'downscaleR'.\cr +The components are the following: + \itemize{ + \item{'mod' is the array that contains the experimental data. It has the + attribute 'dimensions' associated to a vector of strings with the labels + of each dimension of the array, in order.} + \item{'obs' is the array that contains the observational data. It has + the attribute 'dimensions' associated to a vector of strings with the + labels of each dimension of the array, in order.} + \item{'obs' is the array that contains the observational data.} + \item{'lat' and 'lon' are the latitudes and longitudes of the grid into + which the data is interpolated (0 if the loaded variable is a global + mean or the output is an area average).\cr + Both have the attribute 'cdo_grid_des' associated with a character + string with the name of the common grid of the data, following the CDO + naming conventions for grids.\cr + The attribute 'projection' is kept for compatibility with 'downscaleR'. + } + \item{'Variable' has the following components: + \itemize{ + \item{'varName', with the short name of the loaded variable as + specified in the parameter 'var'.} + \item{'level', with information on the pressure level of the variable. + Is kept to NULL by now.} + } + And the following attributes: + \itemize{ + \item{'is_standard', kept for compatibility with 'downscaleR', + tells if a dataset has been homogenized to standards with + 'downscaleR' catalogs.} + \item{'units', a character string with the units of measure of the + variable, as found in the source files.} + \item{'longname', a character string with the long name of the + variable, as found in the source files.} + \item{'daily_agg_cellfun', 'monthly_agg_cellfun', 'verification_time', + kept for compatibility with 'downscaleR'.} + } + } + \item{'Datasets' has the following components: + \itemize{ + \item{'exp', a named list where the names are the identifying + character strings of each experiment in 'exp', each associated to a + list with the following components: + \itemize{ + \item{'members', a list with the names of the members of the + dataset.} + \item{'source', a path or URL to the source of the dataset.} + } + } + \item{'obs', similar to 'exp' but for observational datasets.} + } + } + \item{'Dates', with the follwing components: + \itemize{ + \item{'start', an array of dimensions (sdate, time) with the POSIX + initial date of each forecast time of each starting date.} + \item{'end', an array of dimensions (sdate, time) with the POSIX + final date of each forecast time of each starting date.} + } + } + \item{'InitializationDates', a vector of starting dates as specified in + 'sdates', in POSIX format.} + \item{'when', a time stamp of the date the \code{Load()} call to obtain + the data was issued.} + \item{'source_files', a vector of character strings with complete paths + to all the found files involved in the \code{Load()} call.} + \item{'not_found_files', a vector of character strings with complete + paths to not found files involved in the \code{Load()} call.} + } +} +\details{ +The two output matrices have between 2 and 6 dimensions:\cr + \enumerate{ + \item{Number of experimental/observational datasets.} + \item{Number of members.} + \item{Number of startdates.} + \item{Number of leadtimes.} + \item{Number of latitudes (optional).} + \item{Number of longitudes (optional).} + } +but the two matrices have the same number of dimensions and only the first +two dimensions can have different lengths depending on the input arguments. +For a detailed explanation of the process, read the documentation attached +to the package or check the comments in the code. } \examples{ # Let's assume we want to perform verification with data of a variable @@ -505,24 +796,24 @@ History:\cr # # Example 1: Providing lists of lists to 'exp' and 'obs': # - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') exp <- list( - name = 'experiment', - path = file.path(data_path, 'model/$EXP_NAME$/monthly_mean', - '$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATES$.nc') - ) + name = 'experiment', + path = file.path(data_path, 'model/$EXP_NAME$/monthly_mean', + '$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATES$.nc') + ) obs <- list( - name = 'observation', - path = file.path(data_path, 'observation/$OBS_NAME$/monthly_mean', - '$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') - ) + name = 'observation', + path = file.path(data_path, 'observation/$OBS_NAME$/monthly_mean', + '$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') + ) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(exp), list(obs), startDates, - output = 'areave', latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } + output = 'areave', latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } # # Example 2: Providing vectors of character strings to 'exp' and 'obs' # and using a configuration file. @@ -531,20 +822,20 @@ sampleData <- Load('tos', list(exp), list(obs), startDates, # has the proper entries to load these (see ?LoadConfigFile for details on # writing a configuration file). # - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') expA <- list(name = 'experiment', path = file.path(data_path, - 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', - '$VAR_NAME$_$START_DATE$.nc')) + 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', + '$VAR_NAME$_$START_DATE$.nc')) obsX <- list(name = 'observation', path = file.path(data_path, - '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', - '$VAR_NAME$_$YEAR$$MONTH$.nc')) + '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', + '$VAR_NAME$_$YEAR$$MONTH$.nc')) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(expA), list(obsX), startDates, - output = 'areave', latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) + output = 'areave', latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) # # Example 2: providing character strings in 'exp' and 'obs', and providing # a configuration file. @@ -561,26 +852,35 @@ data_path <- system.file('sample_data', package = 's2dverification') exp_data_path <- paste0(data_path, '/model/$EXP_NAME$/') obs_data_path <- paste0(data_path, '/$OBS_NAME$/') c <- ConfigAddEntry(c, 'experiments', dataset_name = 'experiment', - var_name = 'tos', main_path = exp_data_path, - file_path = '$STORE_FREQ$_mean/$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATE$.nc') + var_name = 'tos', main_path = exp_data_path, + file_path = '$STORE_FREQ$_mean/$VAR_NAME$_3hourly/$VAR_NAME$_$START_DATE$.nc') c <- ConfigAddEntry(c, 'observations', dataset_name = 'observation', - var_name = 'tos', main_path = obs_data_path, - file_path = '$STORE_FREQ$_mean/$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') + var_name = 'tos', main_path = obs_data_path, + file_path = '$STORE_FREQ$_mean/$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc') ConfigFileSave(c, configfile, confirm = FALSE) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', c('experiment'), c('observation'), startDates, - output = 'areave', latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40, configfile = configfile) - } - \dontshow{ + output = 'areave', latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40, configfile = configfile) + } + \dontshow{ startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - output = 'areave', - latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } + c('observation'), startDates, + output = 'areave', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } +} +\author{ +History:\cr +0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@bsc.es}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Formatting to CRAN\cr +1.2 - 2015-02 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Generalisation + parallelisation\cr +1.3 - 2015-07 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Improvements related to configuration file mechanism\cr +1.4 - 2016-01 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Added subsetting capabilities } \keyword{datagen} + diff --git a/man/Mean1Dim.Rd b/man/Mean1Dim.Rd index 0d56d083327c9db4d8f6b80de3157878d9fbdd9c..613fc468ed0a3f67019b2688f47e398951c8d8ab 100644 --- a/man/Mean1Dim.Rd +++ b/man/Mean1Dim.Rd @@ -1,30 +1,29 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Mean1Dim.R \name{Mean1Dim} \alias{Mean1Dim} -\title{ -Averages An Array Along A Dimension -} -\description{ -Averages the array along the posdim dimension along the user specified dimension. The user can specify a subset of the dimension to take the mean along. -} +\title{Averages An Array Along A Dimension} \usage{ Mean1Dim(var, posdim, narm = TRUE, limits = NULL) } \arguments{ - \item{var}{ -Matrix to average. - } - \item{posdim}{ -Dimension to average along. - } - \item{narm}{ -Ignore NA (TRUE) values or not (FALSE). - } - \item{limits}{ -Limits to average between. Default is to take the mean along the entire dimension. - } +\item{var}{Matrix to average.} + +\item{posdim}{Dimension to average along.} + +\item{narm}{Ignore NA (TRUE) values or not (FALSE).} + +\item{limits}{Limits to average between. Default is to take the mean along +the entire dimension.} } \value{ -Array with one dimension less than the input array, containing the average along the posdim dimension. +Array with one dimension less than the input array, containing + the average along the posdim dimension. +} +\description{ +Averages the array along the posdim dimension along the user specified +dimension. The user can specify a subset of the dimension to take the mean +along. } \examples{ a <- array(rnorm(24), dim = c(2, 3, 4)) @@ -33,7 +32,8 @@ print(Mean1Dim(a, 2)) } \author{ History:\cr -0.1 - 2011-04 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to R CRAN +0.1 - 2011-04 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to R CRAN } \keyword{datagen} + diff --git a/man/MeanListDim.Rd b/man/MeanListDim.Rd index f3667d7543e394ee1c1131e533054ba62e985556..98e07c8eccbaeba6fbc41394fc0a5a809ee0805a 100644 --- a/man/MeanListDim.Rd +++ b/man/MeanListDim.Rd @@ -1,27 +1,24 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/MeanListDim.R \name{MeanListDim} \alias{MeanListDim} -\title{ -Averages An Array Along Multiple Dimensions -} -\description{ -Averages an array along a set of dimensions given by the argument dims. -} +\title{Averages An Array Along Multiple Dimensions} \usage{ MeanListDim(var, dims, narm = TRUE) } \arguments{ - \item{var}{ -Input array. - } - \item{dims}{ -List of dimensions to average along. - } - \item{narm}{ -Ignore NA (TRUE) values or not (FALSE). - } +\item{var}{Input array.} + +\item{dims}{List of dimensions to average along.} + +\item{narm}{Ignore NA (TRUE) values or not (FALSE).} } \value{ -The averaged array, with the dimensions specified in \code{dims} removed. +The averaged array, with the dimensions specified in \code{dims} + removed. +} +\description{ +Averages an array along a set of dimensions given by the argument dims. } \examples{ a <- array(rnorm(24), dim = c(2, 3, 4)) @@ -36,3 +33,4 @@ History:\cr 1.1 - 2015-03 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Improved memory usage } \keyword{datagen} + diff --git a/man/NAO.Rd b/man/NAO.Rd index c0963652762d4fade328e86cb17bca4927424260..2767f7e857f6b0806d3559c41484a94d336265e8 100644 --- a/man/NAO.Rd +++ b/man/NAO.Rd @@ -1,95 +1,93 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/NAO.R \name{NAO} \alias{NAO} -\title{ -Computes the North Atlantic Oscillation (NAO) Index -} -\description{ -Compute the North Atlantic Oscillation (NAO) index based on -the leading EOF of the sea level pressure (SLP) anomalies over the -north Atlantic region (20N-80N, 80W-40E). The PCs are obtained by projecting -the forecast and observed anomalies onto the observed EOF pattern (Pobs) or the -forecast anomalies onto the EOF pattern of the other years of the forecast -(Pmod). By default (ftime_average = 2:4) NAO() computes the NAO index for -1-month lead seasonal forecasts that can be plotted with BoxPlot(). Returns -cross-validated PCs of the NAO index for forecast (ano_exp) and observations -(ano_obs) based on the leading EOF pattern.\cr -} +\title{Computes the North Atlantic Oscillation (NAO) Index} \usage{ -NAO(ano_exp = NULL, ano_obs = NULL, lon, lat, ftime_average = 2:4, - obsproj = TRUE) +NAO(ano_exp = NULL, ano_obs = NULL, lon, lat, ftime_average = 2:4, + obsproj = TRUE) } \arguments{ - \item{ano_exp}{ -Array of North Atlantic SLP (20N-80N, 80W-40E) forecast anomalies from -\code{Ano()} or \code{Ano_CrossValid()} with dimensions (n. of experimental -data sets, n. of ensemble members, n. of start dates, n. of forecast time -steps, n. of latitudes, n. of longitudes). If only NAO of observational data -needs to be computed, this parameter can be left to NULL (default). - } - \item{ano_obs}{ -Array of North Atlantic SLP (20N-80N, 80W-40E) observed anomalies from -\code{Ano()} or \code{Ano_CrossValid()} with dimensions (n. of observational -data sets, n. of obs. ensemble members, n. of start dates, n. of forecast time -steps, n. of latitudes, n. of longitudes). If only NAO of experimental data -needs to be computed, this parameter can be left to NULL (default). - } - \item{lon}{ -Vector with the longitudes of \code{ano_exp} and \code{ano_obs}. - } - \item{lat}{ -Vector with the latitudes of \code{ano_exp} and \code{ano_obs}. - } - \item{ftime_average}{ -A vector with the forecast time steps to average across defining the target -period. Takes by default 2:4, i.e. from 2nd to 4th forecast time steps. - } - \item{obsproj}{ -\code{obsproj = TRUE} will compute the NAO index by projecting the forecast -anomalies onto the leading EOF of observational reference.\cr +\item{ano_exp}{Array of North Atlantic SLP (20N-80N, 80W-40E) forecast +anomalies from \code{Ano()} or \code{Ano_CrossValid()} with dimensions +(n. of experimental data sets, n. of ensemble members, n. of start dates, +n. of forecast time steps, n. of latitudes, n. of longitudes). If only +NAO of observational data needs to be computed, this parameter can be left +to NULL (default).} + +\item{ano_obs}{Array of North Atlantic SLP (20N-80N, 80W-40E) observed +anomalies from \code{Ano()} or \code{Ano_CrossValid()} with dimensions +(n. of observational data sets, n. of obs. ensemble members, +n. of start dates, n. of forecast time steps, n. of latitudes, +n. of longitudes). If only NAO of experimental data needs to be computed, +this parameter can be left to NULL (default).} + +\item{lon}{Vector with the longitudes of \code{ano_exp} and \code{ano_obs}.} + +\item{lat}{Vector with the latitudes of \code{ano_exp} and \code{ano_obs}.} + +\item{ftime_average}{A vector with the forecast time steps to average across +defining the target period. Takes by default 2:4, i.e. from 2nd to 4th +forecast time steps.} + +\item{obsproj}{\code{obsproj = TRUE} will compute the NAO index by +projecting the forecast anomalies onto the leading EOF of observational +reference.\cr \code{obsproj = FALSE} will compute the NAO by first computing the leading -EOF of the forecast anomalies (in cross-validation mode, i.e. leaving the year -you are evaluating out), and then projecting forecast anomalies onto this EOF. - } +EOF of the forecast anomalies (in cross-validation mode, i.e. leaving the +year you are evaluating out), and then projecting forecast anomalies onto +this EOF.} } \value{ - \item{NAO_exp}{ -Array of forecast NAO index in verification format (ensemble members, -start dates). - } - \item{NAO_obs}{ -Array of observed NAO index in verification format (1, number of start -dates). - } - \item{EOFs_obs}{ -EOFs of the observational references. - } +\item{NAO_exp}{ + Array of forecast NAO index in verification format (ensemble members, + start dates). + } +\item{NAO_obs}{ + Array of observed NAO index in verification format (1, number of start + dates). +} +\item{EOFs_obs}{ + EOFs of the observational references. +} +} +\description{ +Compute the North Atlantic Oscillation (NAO) index based on the leading EOF +of the sea level pressure (SLP) anomalies over the north Atlantic region +(20N-80N, 80W-40E). The PCs are obtained by projecting the forecast and +observed anomalies onto the observed EOF pattern (Pobs) or the forecast +anomalies onto the EOF pattern of the other years of the forecast (Pmod). +By default (ftime_average = 2:4) NAO() computes the NAO index for 1-month +lead seasonal forecasts that can be plotted with BoxPlot(). Returns +cross-validated PCs of the NAO index for forecast (ano_exp) and observations +(ano_obs) based on the leading EOF pattern. } \examples{ # See examples on Load() to understand the first lines in this example - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') expA <- list(name = 'experiment', path = file.path(data_path, - 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', - '$VAR_NAME$_$START_DATE$.nc')) + 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', + '$VAR_NAME$_$START_DATE$.nc')) obsX <- list(name = 'observation', path = file.path(data_path, - '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', - '$VAR_NAME$_$YEAR$$MONTH$.nc')) + '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', + '$VAR_NAME$_$YEAR$$MONTH$.nc')) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(expA), list(obsX), startDates, - leadtimemin = 1, leadtimemax = 4, output = 'lonlat', - latmin = 20, latmax = 90, lonmin = -80, lonmax = 40) - } - \dontshow{ + leadtimemin = 1, leadtimemax = 4, output = 'lonlat', + latmin = 20, latmax = 90, lonmin = -80, lonmax = 40) + } + \dontshow{ startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - leadtimemin = 1, - leadtimemax = 4, - output = 'lonlat', - latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) + c('observation'), startDates, + leadtimemin = 1, + leadtimemax = 4, + output = 'lonlat', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) # No example data is available over NAO region, so in this example we will # tweak the available data. In a real use case, one can Load() the data over # NAO region directly. @@ -100,7 +98,7 @@ attr(sampleData$lon, 'data_across_gw') <- TRUE sampleData$lat[] <- c(20, 80) attr(sampleData$lat, 'first_lat') <- 20 attr(sampleData$lat, 'last_lat') <- 80 - } + } # Now ready to compute the EOFs and project on, for example, the first # variability mode. @@ -110,24 +108,27 @@ ano <- Ano_CrossValid(sampleData$mod, sampleData$obs) nao <- NAO(ano$ano_exp, ano$ano_obs, sampleData$lon, sampleData$lat) # Finally plot the NAO index PlotBoxWhisker(nao$NAO_exp, nao$NAO_obs, "NAO index, DJF", "NAO index (PC1) TOS", - monini = 12, yearini = 1985, freq = 1, "Exp. A", "Obs. X") -} -\references{ -Doblas-Reyes, F.J., Pavan, V. and Stephenson, D. (2003). The skill of -multi-model seasonal forecasts of the wintertime North Atlantic Oscillation. -Climate Dynamics, 21, 501-514. DOI: 10.1007/s00382-003-0350-4 + monini = 12, yearini = 1985, freq = 1, "Exp. A", "Obs. X") + } \author{ History:\cr -0.1 - 2013-08 (F. Lienert, \email{flienert at ic3.cat}) - Original code\cr -0.2 - 2014-03 (V. Guemas, \email{virginie.guemas at bsc.es}) - Removing the -rotation\cr -0.3 - 2014-05 (L. Batte, \email{lauriane.batte at ic3.cat}) - Changes to -simplify function and add Pobs and Pmod options for NAO projection -calculations\cr -0.4 - 2015-03 (L. Batte, \email{lauriane.batte at ic3.cat}) - Polarity -check and correction is wrong. Switched to have a negative NAO index when the -anomaly pattern corresponds to NAO-. -1.0 - 2016-03 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Formatted to CRAN +0.1 - 2013-08 (F. Lienert, \email{flienert@ic3.cat}) - Original code\cr +0.2 - 2014-03 (V. Guemas, \email{virginie.guemas@bsc.es}) - Removing the + rotation\cr +0.3 - 2014-05 (L. Batte, \email{lauriane.batte@ic3.cat}) - Changes to + simplify function and add Pobs and Pmod options for NAO projection + calculations\cr +0.4 - 2015-03 (L. Batte, \email{lauriane.batte@ic3.cat}) - Polarity + check and correction is wrong. Switched to have a negative NAO index when the + anomaly pattern corresponds to NAO-. +1.0 - 2016-03 (N. Manubens, \email{nicolau.manubens@bsc.es}) - + Formatted to CRAN +} +\references{ +Doblas-Reyes, F.J., Pavan, V. and Stephenson, D. (2003). The skill of + multi-model seasonal forecasts of the wintertime North Atlantic Oscillation. + Climate Dynamics, 21, 501-514. DOI: 10.1007/s00382-003-0350-4 } \keyword{datagen} + diff --git a/man/Plot2VarsVsLTime.Rd b/man/Plot2VarsVsLTime.Rd index faeaed7961bbfb9dff754629ed460245bc3a1ae8..e79fb34edfae731da6e1409f6365726b6db3f01b 100644 --- a/man/Plot2VarsVsLTime.Rd +++ b/man/Plot2VarsVsLTime.Rd @@ -1,103 +1,88 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Plot2VarsVsLTime.R \name{Plot2VarsVsLTime} \alias{Plot2VarsVsLTime} -\title{ -Plot Two Scores With Confidence Intervals In A Common Plot +\title{Plot Two Scores With Confidence Intervals In A Common Plot} +\usage{ +Plot2VarsVsLTime(var1, var2, toptitle = "", ytitle = "", monini = 1, + freq = 12, nticks = NULL, limits = NULL, listexp = c("exp1", "exp2", + "exp3"), listvars = c("var1", "var2"), biglab = FALSE, hlines = NULL, + leg = TRUE, siglev = FALSE, sizetit = 1, show_conf = TRUE, + fileout = "output_plot2varsvsltime.eps", width = 8, height = 5, + size_units = "in", res = 100, ...) +} +\arguments{ +\item{var1}{Matrix of dimensions (nexp/nmod, nltime).} + +\item{var2}{Matrix of dimensions (nexp/nmod, nltime).} + +\item{toptitle}{Main title, optional.} + +\item{ytitle}{Title of Y-axis, optional.} + +\item{monini}{Starting month between 1 and 12. Default = 1.} + +\item{freq}{1 = yearly, 12 = monthly, 4 = seasonal, ... Default = 12.} + +\item{nticks}{Number of ticks and labels on the x-axis, optional.} + +\item{limits}{c(lower limit, upper limit): limits of the Y-axis, optional.} + +\item{listexp}{List of experiment names, up to three, optional.} + +\item{listvars}{List of names of input variables, optional.} + +\item{biglab}{TRUE/FALSE for presentation/paper plot. Default = FALSE.} + +\item{hlines}{c(a, b, ...) Add horizontal black lines at Y-positions a, b, +...\cr +Default: NULL.} + +\item{leg}{TRUE/FALSE if legend should be added or not to the plot. +Default = TRUE.} + +\item{siglev}{TRUE/FALSE if significance level should replace confidence +interval.\cr +Default = FALSE.} + +\item{sizetit}{Multiplicative factor to change title size, optional.} + +\item{show_conf}{TRUE/FALSE to show/not confidence intervals for input +variables.} + +\item{fileout}{Name of output file. Extensions allowed: eps/ps, jpeg, png, +pdf, bmp and tiff. \cr +Default = 'output_plot2varsvsltime.eps'} + +\item{width}{File width, in the units specified in the parameter size_units +(inches by default). Takes 8 by default.} + +\item{height}{File height, in the units specified in the parameter +size_units (inches by default). Takes 5 by default.} + +\item{size_units}{Units of the size of the device (file or window) to plot +in. Inches ('in') by default. See ?Devices and the creator function of the +corresponding device.} + +\item{res}{Resolution of the device (file or window) to plot in. See +?Devices and the creator function of the corresponding device.} + +\item{...}{Arguments to be passed to the method. Only accepts the following +graphical parameters:\cr +adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt +csi cxy err family fg fig font font.axis font.lab font.main font.sub lend +lheight ljoin lmitre mar mex mfcol mfrow mfg mkh oma omd omi page pch plt +smo srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog \cr +For more information about the parameters see `par`.} } \description{ Plots two input variables having the same dimensions in a common plot.\cr One plot for all experiments.\cr Input variables should have dimensions (nexp/nmod, nltime). } -\usage{ -Plot2VarsVsLTime(var1, var2, toptitle = "", ytitle = "", monini = 1, - freq = 12, nticks = NULL, limits = NULL, - listexp = c("exp1", "exp2", "exp3"), - listvars = c("var1", "var2"), biglab = FALSE, hlines = NULL, - leg = TRUE, siglev = FALSE, sizetit = 1, show_conf = TRUE, - fileout = "output_plot2varsvsltime.eps", - width = 8, height = 5, size_units = 'in', res = 100, ...) -} -\arguments{ - \item{var1}{ -Matrix of dimensions (nexp/nmod, nltime). - } - \item{var2}{ -Matrix of dimensions (nexp/nmod, nltime). - } - \item{toptitle}{ -Main title, optional. - } - \item{ytitle}{ -Title of Y-axis, optional. - } - \item{monini}{ -Starting month between 1 and 12. Default = 1. - } - \item{freq}{ -1 = yearly, 12 = monthly, 4 = seasonal, ... Default = 12. - } - \item{nticks}{ -Number of ticks and labels on the x-axis, optional. - } - \item{limits}{ -c(lower limit, upper limit): limits of the Y-axis, optional. - } - \item{listexp}{ -List of experiment names, up to three, optional. - } - \item{listvars}{ -List of names of input variables, optional. - } - \item{biglab}{ -TRUE/FALSE for presentation/paper plot. Default = FALSE. - } - \item{hlines}{ -c(a, b, ...) Add horizontal black lines at Y-positions a, b, ...\cr -Default: NULL. - } - \item{leg}{ -TRUE/FALSE if legend should be added or not to the plot. Default = TRUE. - } - \item{siglev}{ -TRUE/FALSE if significance level should replace confidence interval.\cr -Default = FALSE. - } - \item{sizetit}{ -Multiplicative factor to change title size, optional. - } - \item{show_conf}{ -TRUE/FALSE to show/not confidence intervals for input variables. - } - \item{fileout}{ -Name of output file. Extensions allowed: eps/ps, jpeg, png, pdf, bmp -and tiff. \cr -Default = 'output_plot2varsvsltime.eps' - } - \item{width}{ -File width, in the units specified in the parameter size_units (inches by default). Takes 8 by default. - } - \item{height}{ -File height, in the units specified in the parameter size_units (inches by default). Takes 5 by default. - } - \item{size_units}{ -Units of the size of the device (file or window) to plot in. Inches ('in') by default. See ?Devices and the creator function of the corresponding device. - } - \item{res}{ -Resolution of the device (file or window) to plot in. See ?Devices and the creator function of the corresponding device. - } - \item{...}{ - Arguments to be passed to the method. Only accepts the following - graphical parameters: - - adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt csi cxy err family fg fig font font.axis font.lab font.main font.sub lend lheight ljoin lmitre mar mex mfcol mfrow mfg mkh oma omd omi page pch plt smo srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog - - For more information about the parameters see `par` - } -} \details{ Examples of input:\cr -------------------\cr -\cr +------------------\cr\cr RMSE error for a number of experiments and along lead-time: (nexp, nltime) } \examples{ @@ -114,20 +99,23 @@ dim_to_mean <- 2 # Mean along members required_complete_row <- 3 # Discard start dates that contain NA along lead-times leadtimes_per_startdate <- 60 rms <- RMS(Mean1Dim(smooth_ano_exp, dim_to_mean), - Mean1Dim(smooth_ano_obs, dim_to_mean), - compROW = required_complete_row, - limits = c(ceiling((runmean_months + 1) / 2), - leadtimes_per_startdate - floor(runmean_months / 2))) + Mean1Dim(smooth_ano_obs, dim_to_mean), + compROW = required_complete_row, + limits = c(ceiling((runmean_months + 1) / 2), + leadtimes_per_startdate - floor(runmean_months / 2))) smooth_ano_exp_m_sub <- smooth_ano_exp - InsertDim(Mean1Dim(smooth_ano_exp, 2, - narm = TRUE), 2, dim(smooth_ano_exp)[2]) + narm = TRUE), 2, dim(smooth_ano_exp)[2]) spread <- Spread(smooth_ano_exp_m_sub, c(2, 3)) Plot2VarsVsLTime(InsertDim(rms[, , , ], 1, 1), spread$sd, - toptitle = 'RMSE and spread', monini = 11, freq = 12, - listexp = c('CMIP5 IC3'), listvar = c('RMSE', 'spread'), - fileout = 'plot2vars.eps') + toptitle = 'RMSE and spread', monini = 11, freq = 12, + listexp = c('CMIP5 IC3'), listvar = c('RMSE', 'spread'), + fileout = 'plot2vars.eps') + } \author{ History:\cr -1.0 - 2013-03 (I. Andreu-Burillo, \email{isabel.andreu-burillo at ic3.cat}) - Original code +1.0 - 2013-03 (I. Andreu-Burillo, \email{isabel.andreu-burillo@ic3.cat}) + - Original code } \keyword{dynamic} + diff --git a/man/PlotACC.Rd b/man/PlotACC.Rd index dc4b5c8759e70c29eed21e081c219ca0368f6c8d..3427f652e8d76ff3a93ec9295f2cf47497237092 100644 --- a/man/PlotACC.Rd +++ b/man/PlotACC.Rd @@ -1,128 +1,123 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/PlotACC.R \name{PlotACC} \alias{PlotACC} -\title{ -Plot Plumes/Timeseries Of Anomaly Correlation Coefficients -} -\description{ -Plots plumes/timeseries of ACC from an array with dimensions (output from \code{ACC()}): \cr - c(nexp, nobs, nsdates, nltime, 4)\cr -where the fourth dimension is of length 4 and contains the lower limit of the 95\% confidence interval, the ACC, the upper limit of the 95\% confidence interval and the 95\% significance level given by a one-sided T-test. -} +\title{Plot Plumes/Timeseries Of Anomaly Correlation Coefficients} \usage{ -PlotACC(ACC, sdates, toptitle = "", sizetit = 1, ytitle = "", limits = NULL, - legends = NULL, freq = 12, biglab = FALSE, fill = FALSE, - linezero = FALSE, points = TRUE, vlines = NULL, - fileout = "output_PlotACC.eps", - width = 8, height = 5, size_units = 'in', res = 100, ...) +PlotACC(ACC, sdates, toptitle = "", sizetit = 1, ytitle = "", + limits = NULL, legends = NULL, freq = 12, biglab = FALSE, + fill = FALSE, linezero = FALSE, points = TRUE, vlines = NULL, + fileout = "output_PlotACC.eps", width = 8, height = 5, + size_units = "in", res = 100, ...) } \arguments{ - \item{ACC}{ -ACC matrix with with dimensions:\cr - c(nexp, nobs, nsdates, nltime, 4)\cr -with the fourth dimension of length 4 containing the lower limit of the 95\% confidence interval, the ACC, the upper limit of the 95\% confidence interval and the 95\% significance level. - } - \item{sdates}{ -List of startdates: c('YYYYMMDD','YYYYMMDD'). - } - \item{toptitle}{ -Main title, optional. - } - \item{sizetit}{ -Multiplicative factor to scale title size, optional. - } - \item{ytitle}{ -Title of Y-axis for each experiment: c('',''), optional. - } - \item{limits}{ -c(lower limit, upper limit): limits of the Y-axis, optional. - } - \item{legends}{ -List of flags (characters) to be written in the legend, optional. - } - \item{freq}{ -1 = yearly, 12 = monthly, 4 = seasonal, ... Default: 12. - } - \item{biglab}{ -TRUE/FALSE for presentation/paper plot, Default = FALSE. - } - \item{fill}{ -TRUE/FALSE if filled confidence interval. Default = FALSE. - } - \item{linezero}{ -TRUE/FALSE if a line at y=0 should be added. Default = FALSE. - } - \item{points}{ -TRUE/FALSE if points instead of lines. Default = TRUE.\cr -Must be TRUE if only 1 leadtime. - } - \item{vlines}{ -List of x location where to add vertical black lines, optional. - } - \item{fileout}{ -Name of output file. Extensions allowed: eps/ps, jpeg, png, pdf, bmp -and tiff. \cr -Default = 'output_PlotACC.eps' - } - \item{width}{ -File width, in the units specified in the parameter size_units (inches by default). Takes 8 by default. - } - \item{height}{ -File height, in the units specified in the parameter size_units (inches by default). Takes 5 by default. - } - \item{size_units}{ -Units of the size of the device (file or window) to plot in. Inches ('in') by default. See ?Devices and the creator function of the corresponding device. - } - \item{res}{ -Resolution of the device (file or window) to plot in. See ?Devices and the creator function of the corresponding device. - } - \item{...}{ - Arguments to be passed to the method. Only accepts the following - graphical parameters: - - adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt csi cxy err family fg fig fin font font.axis font.lab font.main font.sub lend lheight ljoin lmitre mar mex mfcol mfrow mfg mkh oma omd omi page plt smo srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog - - For more information about the parameters see `par` - } +\item{ACC}{ACC matrix with with dimensions:\cr +c(nexp, nobs, nsdates, nltime, 4)\cr +with the fourth dimension of length 4 containing the lower limit of the +95\% confidence interval, the ACC, the upper limit of the 95\% confidence +interval and the 95\% significance level.} + +\item{sdates}{List of startdates: c('YYYYMMDD','YYYYMMDD').} + +\item{toptitle}{Main title, optional.} + +\item{sizetit}{Multiplicative factor to scale title size, optional.} + +\item{ytitle}{Title of Y-axis for each experiment: c('',''), optional.} + +\item{limits}{c(lower limit, upper limit): limits of the Y-axis, optional.} + +\item{legends}{List of flags (characters) to be written in the legend, +optional.} + +\item{freq}{1 = yearly, 12 = monthly, 4 = seasonal, ... Default: 12.} + +\item{biglab}{TRUE/FALSE for presentation/paper plot, Default = FALSE.} + +\item{fill}{TRUE/FALSE if filled confidence interval. Default = FALSE.} + +\item{linezero}{TRUE/FALSE if a line at y=0 should be added. Default = FALSE.} + +\item{points}{TRUE/FALSE if points instead of lines. Default = TRUE.\cr +Must be TRUE if only 1 leadtime.} + +\item{vlines}{List of x location where to add vertical black lines, optional.} + +\item{fileout}{Name of output file. Extensions allowed: eps/ps, jpeg, png, +pdf, bmp and tiff. \cr +Default = 'output_PlotACC.eps'} + +\item{width}{File width, in the units specified in the parameter size_units +(inches by default). Takes 8 by default.} + +\item{height}{File height, in the units specified in the parameter +size_units (inches by default). Takes 5 by default.} + +\item{size_units}{Units of the size of the device (file or window) to plot +in. Inches ('in') by default. See ?Devices and the creator function of the +corresponding device.} + +\item{res}{Resolution of the device (file or window) to plot in. See +?Devices and the creator function of the corresponding device.} + +\item{\dots}{Arguments to be passed to the method. Only accepts the following +graphical parameters:\cr +adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt +csi cxy err family fg fig fin font font.axis font.lab font.main font.sub +lend lheight ljoin lmitre mar mex mfcol mfrow mfg mkh oma omd omi page +plt smo srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog\cr +For more information about the parameters see `par`.} +} +\description{ +Plots plumes/timeseries of ACC from an array with dimensions +(output from \code{ACC()}): \cr +c(nexp, nobs, nsdates, nltime, 4)\cr +where the fourth dimension is of length 4 and contains the lower limit of +the 95\% confidence interval, the ACC, the upper limit of the 95\% +confidence interval and the 95\% significance level given by a one-sided +T-test. } \examples{ # See examples on Load() to understand the first lines in this example - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') expA <- list(name = 'experiment', path = file.path(data_path, - 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', - '$VAR_NAME$_$START_DATE$.nc')) + 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', + '$VAR_NAME$_$START_DATE$.nc')) obsX <- list(name = 'observation', path = file.path(data_path, - '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', - '$VAR_NAME$_$YEAR$$MONTH$.nc')) + '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', + '$VAR_NAME$_$YEAR$$MONTH$.nc')) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(expA), list(obsX), startDates, - leadtimemin = 1, leadtimemax = 4, output = 'lonlat', - latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) - } - \dontshow{ + leadtimemin = 1, leadtimemax = 4, output = 'lonlat', + latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) + } + \dontshow{ startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - leadtimemin = 1, - leadtimemax = 4, - output = 'lonlat', - latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } + c('observation'), startDates, + leadtimemin = 1, + leadtimemax = 4, + output = 'lonlat', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } sampleData$mod <- Season(sampleData$mod, 4, 11, 12, 2) sampleData$obs <- Season(sampleData$obs, 4, 11, 12, 2) clim <- Clim(sampleData$mod, sampleData$obs) ano_exp <- Ano(sampleData$mod, clim$clim_exp) ano_obs <- Ano(sampleData$obs, clim$clim_obs) acc <- ACC(Mean1Dim(sampleData$mod, 2), - Mean1Dim(sampleData$obs, 2)) + Mean1Dim(sampleData$obs, 2)) PlotACC(acc$ACC, startDates, toptitle = "Anomaly Correlation Coefficient") + } \author{ History:\cr -0.1 - 2013-08 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +0.1 - 2013-08 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{dynamic} + diff --git a/man/PlotAno.Rd b/man/PlotAno.Rd index f36ee3bba1a93cd5ee55107899d5e024c7d575e2..8a42d9fe53aab7e156a2125b56b50cc58a8f5945 100644 --- a/man/PlotAno.Rd +++ b/man/PlotAno.Rd @@ -1,100 +1,90 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/PlotAno.R \name{PlotAno} \alias{PlotAno} -\title{ -Plot Raw Or Smoothed Anomalies -} -\description{ -Plots timeseries of raw or smoothed anomalies of any variable output from \code{Load()} or \code{Ano()} or or \code{Ano_CrossValid()} or \code{Smoothing()}. -} +\title{Plot Raw Or Smoothed Anomalies} \usage{ -PlotAno(exp_ano, obs_ano = NULL, sdates, toptitle = rep("", 15), - ytitle = rep("", 15), limits = NULL, legends = NULL, freq = 12, - biglab = FALSE, fill = TRUE, memb = TRUE, ensmean = TRUE, - linezero = FALSE, points = FALSE, vlines = NULL, sizetit = 1, - fileout = paste0("output", 1:5, "_plotano.eps"), - width = 8, height = 5, size_units = 'in', res = 100, ...) +PlotAno(exp_ano, obs_ano = NULL, sdates, toptitle = rep("", 15), + ytitle = rep("", 15), limits = NULL, legends = NULL, freq = 12, + biglab = FALSE, fill = TRUE, memb = TRUE, ensmean = TRUE, + linezero = FALSE, points = FALSE, vlines = NULL, sizetit = 1, + fileout = paste0("output", 1:5, "_plotano.eps"), width = 8, height = 5, + size_units = "in", res = 100, ...) } \arguments{ - \item{exp_ano}{ -Array containing the experimental data:\cr - c(nmod/nexp, nmemb/nparam, nsdates, nltime). - } - \item{obs_ano}{ -Optional matrix containing the observational data:\cr - c(nobs, nmemb, nsdates, nltime) - } - \item{sdates}{ -List of starting dates: c('YYYYMMDD','YYYYMMDD'). - } - \item{toptitle}{ -Main title for each experiment: c('',''), optional. - } - \item{ytitle}{ -Title of Y-axis for each experiment: c('',''), optional. - } - \item{limits}{ -c(lower limit, upper limit): limits of the Y-axis, optional. - } - \item{legends}{ -List of observational dataset names, optional. - } - \item{freq}{ -1 = yearly, 12 = monthly, 4 = seasonal, ... Default: 12. - } - \item{biglab}{ -TRUE/FALSE for presentation/paper plot. Default = FALSE. - } - \item{fill}{ -TRUE/FALSE if the spread between members should be filled. Default = TRUE. - } - \item{memb}{ -TRUE/FALSE if all members/only the ensemble-mean should be plotted.\cr -Default = TRUE. - } - \item{ensmean}{ -TRUE/FALSE if the ensemble-mean should be plotted. Default = TRUE. - } - \item{linezero}{ -TRUE/FALSE if a line at y=0 should be added. Default = FALSE. - } - \item{points}{ -TRUE/FALSE if points instead of lines should be shown. Default = FALSE. - } - \item{vlines}{ -List of x location where to add vertical black lines, optional. - } - \item{sizetit}{ -Multiplicative factor to scale title size, optional. - } - \item{fileout}{ -Name of the output file for each experiment: c('',''). -Extensions allowed: eps/ps, jpeg, png, pdf, bmp and tiff. If filenames with -different extensions are passed, it will be considered only the first one -and it will be extended to the rest. \cr +\item{exp_ano}{Array containing the experimental data:\cr +c(nmod/nexp, nmemb/nparam, nsdates, nltime).} + +\item{obs_ano}{Optional matrix containing the observational data:\cr +c(nobs, nmemb, nsdates, nltime)} + +\item{sdates}{List of starting dates: c('YYYYMMDD','YYYYMMDD').} + +\item{toptitle}{Main title for each experiment: c('',''), optional.} + +\item{ytitle}{Title of Y-axis for each experiment: c('',''), optional.} + +\item{limits}{c(lower limit, upper limit): limits of the Y-axis, optional.} + +\item{legends}{List of observational dataset names, optional.} + +\item{freq}{1 = yearly, 12 = monthly, 4 = seasonal, ... Default: 12.} + +\item{biglab}{TRUE/FALSE for presentation/paper plot. Default = FALSE.} + +\item{fill}{TRUE/FALSE if the spread between members should be filled. +Default = TRUE.} + +\item{memb}{TRUE/FALSE if all members/only the ensemble-mean should be +plotted.\cr +Default = TRUE.} + +\item{ensmean}{TRUE/FALSE if the ensemble-mean should be plotted. +Default = TRUE.} + +\item{linezero}{TRUE/FALSE if a line at y=0 should be added. +Default = FALSE.} + +\item{points}{TRUE/FALSE if points instead of lines should be shown. +Default = FALSE.} + +\item{vlines}{List of x location where to add vertical black lines, optional.} + +\item{sizetit}{Multiplicative factor to scale title size, optional.} + +\item{fileout}{Name of the output file for each experiment: c('',''). +Extensions allowed: eps/ps, jpeg, png, pdf, bmp and tiff. If filenames +with different extensions are passed, it will be considered only the first +one and it will be extended to the rest. \cr Default = c('output1_plotano.eps', 'output2_plotano.eps', 'output3_plotano.eps', 'output4_plotano.eps', - 'output5_plotano.eps') - } - \item{width}{ -File width, in the units specified in the parameter size_units (inches by default). Takes 8 by default. - } - \item{height}{ -File height, in the units specified in the parameter size_units (inches by default). Takes 5 by default. - } - \item{size_units}{ -Units of the size of the device (file or window) to plot in. Inches ('in') by default. See ?Devices and the creator function of the corresponding device. - } - \item{res}{ -Resolution of the device (file or window) to plot in. See ?Devices and the creator function of the corresponding device. - } - \item{...}{ - Arguments to be passed to the method. Only accepts the following - graphical parameters: - - adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt csi cxy err family fg fig font font.axis font.lab font.main font.sub lend lheight ljoin lmitre mar mex mfcol mfrow mfg mkh oma omd omi page plt smo srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog - - For more information about the parameters see `par` - } + 'output5_plotano.eps')} + +\item{width}{File width, in the units specified in the parameter size_units +(inches by default). Takes 8 by default.} + +\item{height}{File height, in the units specified in the parameter +size_units (inches by default). Takes 5 by default.} + +\item{size_units}{Units of the size of the device (file or window) to plot +in. Inches ('in') by default. See ?Devices and the creator function of the +corresponding device.} + +\item{res}{Resolution of the device (file or window) to plot in. See +?Devices and the creator function of the corresponding device.} + +\item{\dots}{Arguments to be passed to the method. Only accepts the following +graphical parameters:\cr +adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt +csi cxy err family fg fig font font.axis font.lab font.main font.sub lend +lheight ljoin lmitre mar mex mfcol mfrow mfg mkh oma omd omi page plt smo +srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog \cr +For more information about the parameters see `par`.} +} +\description{ +Plots timeseries of raw or smoothed anomalies of any variable output from +\code{Load()} or \code{Ano()} or or \code{Ano_CrossValid()} or +\code{Smoothing()}. } \examples{ # Load sample data as in Load() example: @@ -107,12 +97,14 @@ dim_to_smooth <- 4 # Smooth along lead-times smooth_ano_exp <- Smoothing(ano_exp, runmean_nb_months, dim_to_smooth) smooth_ano_obs <- Smoothing(ano_obs, runmean_nb_months, dim_to_smooth) PlotAno(smooth_ano_exp, smooth_ano_obs, startDates, - toptitle = paste('smoothed anomalies'), ytitle = c('K', 'K', 'K'), - legends = 'ERSST', biglab = FALSE, fileout = 'tos_ano.eps') + toptitle = paste('smoothed anomalies'), ytitle = c('K', 'K', 'K'), + legends = 'ERSST', biglab = FALSE, fileout = 'tos_ano.eps') + } \author{ History:\cr -0.1 - 2011-03 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{dynamic} + diff --git a/man/PlotBoxWhisker.Rd b/man/PlotBoxWhisker.Rd index 31d11d9e00644b84ab8dcf744b7dff4926b94a77..31b7d4d42fdcf4b22f2c264ab33dc2f334a7a8ce 100644 --- a/man/PlotBoxWhisker.Rd +++ b/man/PlotBoxWhisker.Rd @@ -1,115 +1,103 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/PlotBoxWhisker.R \name{PlotBoxWhisker} \alias{PlotBoxWhisker} -\title{ -Box-And-Whisker Plot of Time Series with Ensemble Distribution -} -\description{ -Produce time series of box-and-whisker plot showing the distribution of the -members of a forecast vs. the observed evolution. The correlation between -forecast and observational data is calculated and displayed. Only works for -n-monthly to n-yearly time series. -} +\title{Box-And-Whisker Plot of Time Series with Ensemble Distribution} \usage{ -PlotBoxWhisker(exp, obs, toptitle = '', ytitle = '', monini = 1, yearini = 0, - freq = 1, expname = "exp 1", obsname = "obs 1", drawleg = TRUE, - fileout = "output_PlotBoxWhisker.ps", - width = 8, height = 5, size_units = 'in', res = 100, ...) +PlotBoxWhisker(exp, obs, toptitle = "", ytitle = "", monini = 1, + yearini = 0, freq = 1, expname = "exp 1", obsname = "obs 1", + drawleg = TRUE, fileout = "output_PlotBoxWhisker.ps", width = 8, + height = 5, size_units = "in", res = 100, ...) } \arguments{ - \item{exp}{ -Forecast array of multi-member time series, e.g., the NAO index of one -experiment. The expected dimensions are c(members, -start dates/forecast horizons). A vector with only the time dimension can -also be provided. Only monthly or lower frequency time series are supported. -See parameter freq. - } - \item{obs}{ -Observational vector or array of time series, e.g., the NAO index of the -observations that correspond the forecast data in \code{exp}. +\item{exp}{Forecast array of multi-member time series, e.g., the NAO index +of one experiment. The expected dimensions are +c(members, start dates/forecast horizons). A vector with only the time +dimension can also be provided. Only monthly or lower frequency time +series are supported. See parameter freq.} + +\item{obs}{Observational vector or array of time series, e.g., the NAO index +of the observations that correspond the forecast data in \code{exp}. The expected dimensions are c(start dates/forecast horizons) or c(1, start dates/forecast horizons). Only monthly or lower frequency time -series are supported. See parameter freq. - } - \item{toptitle}{ -Character string to be drawn as figure title. - } - \item{ytitle}{ -Character string to be drawn as y-axis title. - } - \item{monini}{ -Number of the month of the first time step, from 1 to 12. - } - \item{yearini}{ -Year of the first time step. - } - \item{freq}{ -Frequency of the provided time series: 1 = yearly, 12 = monthly, -4 = seasonal, ... Default = 12. - } - \item{expname}{ -Experimental dataset name. - } - \item{obsname}{ -Name of the observational reference dataset. - } - \item{drawleg}{ -TRUE/FALSE: whether to draw the legend or not. - } - \item{fileout}{ -Name of output file. Extensions allowed: eps/ps, jpeg, png, pdf, bmp -and tiff. \cr -Default = 'output_PlotBox.ps' - } - \item{width}{ -File width, in the units specified in the parameter size_units (inches by default). Takes 8 by default. - } - \item{height}{ -File height, in the units specified in the parameter size_units (inches by default). Takes 5 by default. - } - \item{size_units}{ -Units of the size of the device (file or window) to plot in. Inches ('in') by default. See ?Devices and the creator function of the corresponding device. - } - \item{res}{ -Resolution of the device (file or window) to plot in. See ?Devices and the creator function of the corresponding device. - } - \item{...}{ - Arguments to be passed to the method. Only accepts the following - graphical parameters: - - ann ask bg cex.lab cex.sub cin col.axis col.lab col.main col.sub cra crt csi cxy err family fg fig font font.axis font.lab font.main font.sub lend lheight ljoin lmitre mex mfcol mfrow mfg mkh oma omd omi page pin plt pty smo srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog - - For more information about the parameters see `par` - } +series are supported. See parameter freq.} + +\item{toptitle}{Character string to be drawn as figure title.} + +\item{ytitle}{Character string to be drawn as y-axis title.} + +\item{monini}{Number of the month of the first time step, from 1 to 12.} + +\item{yearini}{Year of the first time step.} + +\item{freq}{Frequency of the provided time series: 1 = yearly, 12 = monthly,} + +\item{expname}{Experimental dataset name.} + +\item{obsname}{Name of the observational reference dataset.} + +\item{drawleg}{TRUE/FALSE: whether to draw the legend or not.} + +\item{fileout}{Name of output file. Extensions allowed: eps/ps, jpeg, png, +pdf, bmp and tiff. \cr +Default = 'output_PlotBox.ps'.} + +\item{width}{File width, in the units specified in the parameter size_units +(inches by default). Takes 8 by default.} + +\item{height}{File height, in the units specified in the parameter +size_units (inches by default). Takes 5 by default.} + +\item{size_units}{Units of the size of the device (file or window) to plot +in. Inches ('in') by default. See ?Devices and the creator function of the +corresponding device.} + +\item{res}{Resolution of the device (file or window) to plot in. See +?Devices and the creator function of the corresponding device.} + +\item{...}{Arguments to be passed to the method. Only accepts the following +graphical parameters:\cr +ann ask bg cex.lab cex.sub cin col.axis col.lab col.main col.sub cra crt +csi cxy err family fg fig font font.axis font.lab font.main font.sub lend +lheight ljoin lmitre mex mfcol mfrow mfg mkh oma omd omi page pin plt pty +smo srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog \cr +For more information about the parameters see `par`.} } \value{ Generates a file at the path specified via \code{fileout}. } +\description{ +Produce time series of box-and-whisker plot showing the distribution of the +members of a forecast vs. the observed evolution. The correlation between +forecast and observational data is calculated and displayed. Only works for +n-monthly to n-yearly time series. +} \examples{ # See examples on Load() to understand the first lines in this example - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') expA <- list(name = 'experiment', path = file.path(data_path, - 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', - '$VAR_NAME$_$START_DATE$.nc')) + 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', + '$VAR_NAME$_$START_DATE$.nc')) obsX <- list(name = 'observation', path = file.path(data_path, - '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', - '$VAR_NAME$_$YEAR$$MONTH$.nc')) + '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', + '$VAR_NAME$_$YEAR$$MONTH$.nc')) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(expA), list(obsX), startDates, - leadtimemin = 1, leadtimemax = 4, output = 'lonlat', - latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) - } - \dontshow{ + leadtimemin = 1, leadtimemax = 4, output = 'lonlat', + latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) + } + \dontshow{ startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - leadtimemin = 1, - leadtimemax = 4, - output = 'lonlat', - latmin = 20, latmax = 80, - lonmin = -80, lonmax = 40) + c('observation'), startDates, + leadtimemin = 1, + leadtimemax = 4, + output = 'lonlat', + latmin = 20, latmax = 80, + lonmin = -80, lonmax = 40) # No example data is available over NAO region, so in this example we will # tweak the available data. In a real use case, one can Load() the data over # NAO region directly. @@ -120,23 +108,25 @@ attr(sampleData$lon, 'data_across_gw') <- TRUE sampleData$lat[] <- c(20, 80) attr(sampleData$lat, 'first_lat') <- 20 attr(sampleData$lat, 'last_lat') <- 80 - } + } # Now ready to compute the EOFs and project on, for example, the first # variability mode. ano <- Ano_CrossValid(sampleData$mod, sampleData$obs) nao <- NAO(ano$ano_exp, ano$ano_obs, sampleData$lon, sampleData$lat) # Finally plot the nao index PlotBoxWhisker(nao$NAO_exp, nao$NAO_obs, "NAO index, DJF", "NAO index (PC1) TOS", - monini = 12, yearini = 1985, freq = 1, "Exp. A", "Obs. X") + monini = 12, yearini = 1985, freq = 1, "Exp. A", "Obs. X") + } \author{ History:\cr -0.1 - 2013-09 (F. Lienert, \email{flienert at ic3.cat}) - Original code\cr -0.2 - 2015-03 (L. Batte, \email{lauriane.batte at ic3.cat}) - Removed all\cr -normalization for sake of clarity. -1.0 - 2016-03 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Formatting to R CRAN +0.1 - 2013-09 (F. Lienert, \email{flienert@ic3.cat}) - Original code\cr +0.2 - 2015-03 (L. Batte, \email{lauriane.batte@ic3.cat}) - Removed all\cr + normalization for sake of clarity. +1.0 - 2016-03 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Formatting to R CRAN } \seealso{ EOF, ProjectField, NAO } \keyword{datagen} + diff --git a/man/PlotClim.Rd b/man/PlotClim.Rd index 6840386657c5fb56592d5f20d9f5a7818f4bb525..38c916cbe20c6bac672337c0ff775bf93bc62bd8 100644 --- a/man/PlotClim.Rd +++ b/man/PlotClim.Rd @@ -1,96 +1,88 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/PlotClim.R \name{PlotClim} \alias{PlotClim} -\title{ -Plots Climatologies -} -\description{ -Plots climatologies as a function of the forecast time for any index output from \code{Clim()} and organized in matrix with dimensions:\cr - c(nmod/nexp, nmemb/nparam, nltime) or c(nmod/nexp, nltime) for the experiment data\cr - c(nobs, nmemb, nltime) or c(nobs, nltime) for the observational data -} +\title{Plots Climatologies} \usage{ -PlotClim(exp_clim, obs_clim = NULL, toptitle = "", ytitle = "", monini = 1, - freq = 12, limits = NULL, listexp = c("exp1", "exp2", "exp3"), - listobs = c("obs1", "obs2", "obs3"), biglab = FALSE, leg = TRUE, - sizetit = 1, fileout = "output_plotclim.eps", - width = 8, height = 5, size_units = 'in', res = 100, ...) +PlotClim(exp_clim, obs_clim = NULL, toptitle = "", ytitle = "", + monini = 1, freq = 12, limits = NULL, listexp = c("exp1", "exp2", + "exp3"), listobs = c("obs1", "obs2", "obs3"), biglab = FALSE, + leg = TRUE, sizetit = 1, fileout = "output_plotclim.eps", width = 8, + height = 5, size_units = "in", res = 100, ...) } \arguments{ - \item{exp_clim}{ -Matrix containing the experimental data with dimensions:\cr - c(nmod/nexp, nmemb/nparam, nltime) or c(nmod/nexp, nltime) - } - \item{obs_clim}{ -Matrix containing the observational data (optional) with dimensions:\cr - c(nobs, nmemb, nltime) or c(nobs, nltime) - } - \item{toptitle}{ -Main title, optional - } - \item{ytitle}{ -Title of Y-axis, optional. - } - \item{monini}{ -Starting month between 1 and 12. Default = 1. - } - \item{freq}{ -1 = yearly, 12 = monthly, 4 = seasonal, ... Default = 12. - } - \item{limits}{ -c(lower limit, upper limit): limits of the Y-axis, optional. - } - \item{listexp}{ -List of experiment names, optional. - } - \item{listobs}{ -List of observational dataset names, optional. - } - \item{biglab}{ -TRUE/FALSE for presentation/paper plot. Default = FALSE. - } - \item{leg}{ -TRUE/FALSE to plot the legend or not. - } - \item{sizetit}{ -Multiplicative factor to scale title size, optional. - } - \item{width}{ -File width, in the units specified in the parameter size_units (inches by default). Takes 8 by default. - } - \item{height}{ -File height, in the units specified in the parameter size_units (inches by default). Takes 5 by default. - } - \item{size_units}{ -Units of the size of the device (file or window) to plot in. Inches ('in') by default. See ?Devices and the creator function of the corresponding device. - } - \item{res}{ -Resolution of the device (file or window) to plot in. See ?Devices and the creator function of the corresponding device. - } - \item{fileout}{ -Name of output file. Extensions allowed: eps/ps, jpeg, png, pdf, bmp -and tiff. \cr -Default = 'output_plotclim.eps' - } - \item{...}{ - Arguments to be passed to the method. Only accepts the following - graphical parameters: - - adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt csi cxy err family fg fig font font.axis font.lab font.main font.sub lend lheight ljoin lmitre mar mex mfcol mfrow mfg mkh oma omd omi page pch plt smo srt tck usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog - - For more information about the parameters see `par` - } +\item{exp_clim}{Matrix containing the experimental data with dimensions:\cr +c(nmod/nexp, nmemb/nparam, nltime) or c(nmod/nexp, nltime)} + +\item{obs_clim}{Matrix containing the observational data (optional) with +dimensions:\cr +c(nobs, nmemb, nltime) or c(nobs, nltime)} + +\item{toptitle}{Main title, optional.} + +\item{ytitle}{Title of Y-axis, optional.} + +\item{monini}{Starting month between 1 and 12. Default = 1.} + +\item{freq}{1 = yearly, 12 = monthly, 4 = seasonal, ... Default = 12.} + +\item{limits}{c(lower limit, upper limit): limits of the Y-axis, optional.} + +\item{listexp}{List of experiment names, optional.} + +\item{listobs}{List of observational dataset names, optional.} + +\item{biglab}{TRUE/FALSE for presentation/paper plot. Default = FALSE.} + +\item{leg}{TRUE/FALSE to plot the legend or not.} + +\item{sizetit}{Multiplicative factor to scale title size, optional.} + +\item{fileout}{Name of output file. Extensions allowed: eps/ps, jpeg, png, +pdf, bmp and tiff. \cr +Default = 'output_plotclim.eps'.} + +\item{width}{File width, in the units specified in the parameter size_units +(inches by default). Takes 8 by default.} + +\item{height}{File height, in the units specified in the parameter +size_units (inches by default). Takes 5 by default.} + +\item{size_units}{Units of the size of the device (file or window) to plot +in. Inches ('in') by default. See ?Devices and the creator function of the +corresponding device.} + +\item{res}{Resolution of the device (file or window) to plot in. See +?Devices and the creator function of the corresponding device.} + +\item{...}{Arguments to be passed to the method. Only accepts the following +graphical parameters:\cr +adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt +csi cxy err family fg fig font font.axis font.lab font.main font.sub lend +lheight ljoin lmitre mar mex mfcol mfrow mfg mkh oma omd omi page pch plt +smo srt tck usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog \cr +For more information about the parameters see `par`.} +} +\description{ +Plots climatologies as a function of the forecast time for any index output +from \code{Clim()} and organized in matrix with dimensions:\cr +c(nmod/nexp, nmemb/nparam, nltime) or c(nmod/nexp, nltime) for the +experiment data\cr +c(nobs, nmemb, nltime) or c(nobs, nltime) for the observational data } \examples{ # Load sample data as in Load() example: example(Load) clim <- Clim(sampleData$mod, sampleData$obs) PlotClim(clim$clim_exp, clim$clim_obs, toptitle = paste('climatologies'), - ytitle = 'K', monini = 11, listexp = c('CMIP5 IC3'), - listobs = c('ERSST'), biglab = FALSE, fileout = 'tos_clim.eps') + ytitle = 'K', monini = 11, listexp = c('CMIP5 IC3'), + listobs = c('ERSST'), biglab = FALSE, fileout = 'tos_clim.eps') + } \author{ History:\cr -0.1 - 2011-03 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{datagen} + diff --git a/man/PlotEquiMap.Rd b/man/PlotEquiMap.Rd index 85d92746fc1a62920c6245d6e956146eb55206a4..cb33fc60f2562236a2ef4025c056f28977a15bcc 100644 --- a/man/PlotEquiMap.Rd +++ b/man/PlotEquiMap.Rd @@ -1,248 +1,291 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/PlotEquiMap.R \name{PlotEquiMap} \alias{PlotEquiMap} -\title{ -Maps A Two-Dimensional Variable On A Cylindrical Equidistant Projection -} -\description{ -Map longitude-latitude array (on a regular rectangular or gaussian grid) on a cylindrical equidistant latitude and longitude projection with coloured grid cells. Only the region for which data has been provided is displayed. A colour bar (legend) can be plotted and adjusted. It is possible to draw superimposed arrows, dots, symbols, contour lines and boxes. A number of options is provided to adjust the position, size and colour of the components. This plot function is compatible with figure layouts if colour bar is disabled. -} +\title{Maps A Two-Dimensional Variable On A Cylindrical Equidistant Projection} \usage{ -PlotEquiMap(var, lon, lat, varu = NULL, varv = NULL, - toptitle = NULL, sizetit = NULL, units = NULL, - brks = NULL, cols = NULL, bar_limits = NULL, - triangle_ends = NULL, col_inf = NULL, col_sup = NULL, - colNA = NULL, color_fun = clim.palette(), - square = TRUE, filled.continents = NULL, - coast_color = NULL, coast_width = 1, - contours = NULL, brks2 = NULL, contour_lwd = 0.5, - contour_color = 'black', contour_lty = 1, - contour_label_scale = 1, - dots = NULL, dot_symbol = 4, dot_size = 1, - arr_subsamp = floor(length(lon) / 30), arr_scale = 1, - arr_ref_len = 15, arr_units = "m/s", - arr_scale_shaft = 1, arr_scale_shaft_angle = 1, - axelab = TRUE, labW = FALSE, - intylat = 20, intxlon = 20, - axes_tick_scale = 1, axes_label_scale = 1, - drawleg = TRUE, subsampleg = NULL, - bar_extra_labels = NULL, draw_bar_ticks = TRUE, - draw_separators = FALSE, triangle_ends_scale = 1, - bar_label_digits = 4, bar_label_scale = 1, - units_scale = 1, bar_tick_scale = 1, - bar_extra_margin = rep(0, 4), - boxlim = NULL, boxcol = 'purple2', boxlwd = 5, - margin_scale = rep(1, 4), title_scale = 1, - numbfig = NULL, fileout = NULL, - width = 8, height = 5, size_units = 'in', res = 100, ...) +PlotEquiMap(var, lon, lat, varu = NULL, varv = NULL, toptitle = NULL, + sizetit = NULL, units = NULL, brks = NULL, cols = NULL, + bar_limits = NULL, triangle_ends = NULL, col_inf = NULL, + col_sup = NULL, colNA = NULL, color_fun = clim.palette(), + square = TRUE, filled.continents = NULL, coast_color = NULL, + coast_width = 1, contours = NULL, brks2 = NULL, contour_lwd = 0.5, + contour_color = "black", contour_lty = 1, contour_label_scale = 1, + dots = NULL, dot_symbol = 4, dot_size = 1, + arr_subsamp = floor(length(lon)/30), arr_scale = 1, arr_ref_len = 15, + arr_units = "m/s", arr_scale_shaft = 1, arr_scale_shaft_angle = 1, + axelab = TRUE, labW = FALSE, intylat = 20, intxlon = 20, + axes_tick_scale = 1, axes_label_scale = 1, drawleg = TRUE, + subsampleg = NULL, bar_extra_labels = NULL, draw_bar_ticks = TRUE, + draw_separators = FALSE, triangle_ends_scale = 1, bar_label_digits = 4, + bar_label_scale = 1, units_scale = 1, bar_tick_scale = 1, + bar_extra_margin = rep(0, 4), boxlim = NULL, boxcol = "purple2", + boxlwd = 5, margin_scale = rep(1, 4), title_scale = 1, numbfig = NULL, + fileout = NULL, width = 8, height = 5, size_units = "in", res = 100, + ...) } \arguments{ - \item{var}{ -Array with the values at each cell of a grid on a regular rectangular or gaussian grid. The array is expected to have two dimensions: c(latitude, longitude). Longitudes can be in ascending or descending order and latitudes in any order. It can contain NA values (coloured with 'colNA'). Arrays with dimensions c(longitude, latitude) will also be accepted but 'lon' and 'lat' will be used to disambiguate so this alternative is not appropriate for square arrays. - } - \item{lon}{ -Numeric vector of longitude locations of the cell centers of the grid of 'var', in ascending or descending order (same as 'var'). Expected to be regularly spaced, within either of the ranges [-180, 180] or [0, 360]. Data for two adjacent regions split by the limits of the longitude range can also be provided, e.g. \code{lon = c(0:50, 300:360)} ('var' must be provided consitently). - } - \item{lat}{ -Numeric vector of latitude locations of the cell centers of the grid of 'var', in any order (same as 'var'). Expected to be from a regular rectangular or gaussian grid, within the range [-90, 90]. - } - \item{varu}{ -Array of the zonal component of wind/current/other field with the same dimensions as 'var'. - } - \item{varv}{ -Array of the meridional component of wind/current/other field with the same dimensions as 'var'. - } - \item{toptitle}{ -Top title of the figure, scalable with parameter 'title_scale'. - } - \item{sizetit}{ -Scale factor for the figure top title provided in parameter 'toptitle'. Deprecated. Use 'title_scale' instead. - } - \item{units}{ -Title at the top of the colour bar, most commonly the units of the variable provided in parameter 'var'. - } - \item{brks,cols,bar_limits,triangle_ends}{ -Usually only providing 'brks' is enough to generate the desired colour bar. These parameters allow to define n breaks that define n - 1 intervals to classify each of the values in 'var'. The corresponding grid cell of a given value in 'var' will be coloured in function of the interval it belongs to. These parameters are sent to \code{ColorBar()} to generate the breaks and colours. Additional colours for values beyond the limits of the colour bar are also generated and applied to the plot if 'bar_limits' or 'brks' and 'triangle_ends' are properly provided to do so. See ?ColorBar for a full explanation.\cr - } - \item{col_inf,col_sup,colNA}{ -Colour identifiers to colour the values in 'var' that go beyond the extremes of the colour bar and to colour NA values, respectively. 'colNA' takes attr(cols, 'na_color') if available by default, where cols is the parameter 'cols' if provided or the vector of colors returned by 'color_fun'. If not available, it takes 'pink' by default. 'col_inf' and 'col_sup' will take the value of 'colNA' if not specified. See ?ColorBar for a full explanation on 'col_inf' and 'col_sup'. - } - \item{color_fun,subsampleg,bar_extra_labels,draw_bar_ticks,draw_separators,triangle_ends_scale,bar_label_digits,bar_label_scale,units_scale,bar_tick_scale,bar_extra_margin}{ -Set of parameters to control the visual aspect of the drawn colour bar. See ?ColorBar for a full explanation. - } - \item{square}{ -Logical value to choose either to draw a coloured square for each grid cell in 'var' (TRUE; default) or to draw contour lines and fill the spaces in between with colours (FALSE). In the latter case, 'filled.continents' will take the value FALSE if not specified. - } - \item{filled.continents}{ -Colour to fill in drawn projected continents. Takes the value gray(0.5) by default or, if 'square = FALSE', takes the value FALSE. If set to FALSE, continents are not filled in. - } - \item{coast_color}{ -Colour of the coast line of the drawn projected continents. Takes the value gray(0.5) by default. - } - \item{coast_width}{ -Line width of the coast line of the drawn projected continents. Takes the value 1 by default. - } - \item{contours}{ -Array of same dimensions as 'var' to be added to the plot and displayed with contours. Parameter 'brks2' is required to define the magnitude breaks for each contour curve. Disregarded if 'square = FALSE'. - } - \item{brks2}{ -Vector of magnitude breaks where to draw contour curves for the array provided in 'contours' or if 'square = FALSE'. - } - \item{contour_lwd}{ -Line width of the contour curves provided via 'contours' and 'brks2', or if 'square = FALSE'. - } - \item{contour_color}{ -Line color of the contour curves provided via 'contours' and 'brks2', or if 'square = FALSE'. - } - \item{contour_lty}{ -Line type of the contour curves. Takes 1 (solid) by default. See help on 'lty' in par() for other accepted values. - } - \item{contour_label_scale}{ -Scale factor for the superimposed labels when drawing contour levels. - } - \item{dots}{ -Array of same dimensions as 'var' or with dimensions c(n, dim(var)), where n is the number of dot/symbol layers to add to the plot. A value of TRUE at a grid cell will draw a dot/symbol on the corresponding square of the plot. By default all layers provided in 'dots' are plotted with dots, but a symbol can be specified for each of the layers via the parameter 'dot_symbol'. - } - \item{dot_symbol}{ -Single character/number or vector of characters/numbers that correspond to each of the symbol layers specified in parameter 'dots'. If a single value is specified, it will be applied to all the layers in 'dots'. Takes 15 (centered square) by default. See 'pch' in par() for additional accepted options. - } - \item{dot_size}{ -Scale factor for the dots/symbols to be plotted, specified in 'dots'. If a single value is specified, it will be applied to all layers in 'dots'. Takes 1 by default. - } - \item{arr_subsamp}{ -Subsampling factor to select a subset of arrows in 'varu' and 'varv' to be drawn. Only one out of arr_subsamp arrows will be drawn. Takes 1 by default. - } - \item{arr_scale}{ -Scale factor for drawn arrows from 'varu' and 'varv'. Takes 1 by default. - } - \item{arr_ref_len}{ -Length of the refence arrow to be drawn as legend at the bottom of the figure (in same units as 'varu' and 'varv', only affects the -legend for the wind or variable in these arrays). Defaults to 15. - } - \item{arr_units}{ -Units of 'varu' and 'varv', to be drawn in the legend. Takes 'm/s' by default. - } - \item{arr_scale_shaft}{ -Parameter for the scale of the shaft of the arrows (which also depend on the -number of figures and the arr_scale parameter). Defaults to 1. - } - \item{arr_scale_shaft_angle}{ -Parameter for the scale of the angle of the shaft of the arrows (which also -depend on the number of figure and the arr_scale parameter). Defaults to 1. - } - \item{axelab}{ -Whether to draw longitude and latitude axes or not. TRUE by default. - } - \item{labW}{ -Whether to label the longitude axis with a 'W' instead of minus for negative values. Defaults to FALSE. - } - \item{intylat}{ -Interval between latitude ticks on y-axis, in degrees. Defaults to 20. - } - \item{intxlon}{ -Interval between latitude ticks on x-axis, in degrees. Defaults to 20. - } - \item{axes_tick_scale}{ -Scale factor for the tick lines along the longitude and latitude axes. - } - \item{axes_label_scale}{ -Scale factor for the labels along the longitude and latitude axes. - } - \item{drawleg}{ -Whether to plot a color bar (legend, key) or not. Defaults to TRUE. It is not possible to plot the colour bar if 'add = TRUE'. Use ColorBar() and the return values of PlotEquiMap() instead. - } - \item{boxlim}{ -Limits of a box to be added to the plot, in degrees: c(x1, y1, x2, y2). A list with multiple box specifications can also be provided. - } - \item{boxcol}{ -Colour of the box lines. A vector with a colour for each of the boxes is also accepted. Defaults to 'purple2'. - } - \item{boxlwd}{ -Line width of the box lines. A vector with a line width for each of the boxes is also accepted. Defaults to 5. - } - \item{margin_scale}{ -Scale factor for the margins around the map plot, with the format c(y1, x1, y2, x2). Defaults to rep(1, 4). If drawleg = TRUE, then margin_scale[1] is subtracted 1 unit. - } - \item{title_scale}{ -Scale factor for the figure top title. Defaults to 1. - } - \item{numbfig}{ -Number of figures in the layout the plot will be put into. A higher numbfig will result in narrower margins and smaller labels, axe labels, ticks, thinner lines, ... Defaults to 1. - } - \item{fileout}{ -File where to save the plot. If not specified (default) a graphics device will pop up. Extensions allowed: eps/ps, jpeg, png, pdf, bmp and tiff. \cr - } - \item{width}{ -File width, in the units specified in the parameter size_units (inches by default). Takes 8 by default. - } - \item{height}{ -File height, in the units specified in the parameter size_units (inches by default). Takes 5 by default. - } - \item{size_units}{ -Units of the size of the device (file or window) to plot in. Inches ('in') by default. See ?Devices and the creator function of the corresponding device. - } - \item{res}{ -Resolution of the device (file or window) to plot in. See ?Devices and the creator function of the corresponding device. - } - \item{\dots}{ -Arguments to be passed to the method. Only accepts the following graphical parameters: - -adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt csi cxy err family fg font font.axis font.lab font.main font.sub lend lheight ljoin lmitre mex mfcol mfrow mfg mkh omd omi page pch pin plt pty smo srt tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog - -For more information about the parameters see `par`. - } +\item{var}{Array with the values at each cell of a grid on a regular +rectangular or gaussian grid. The array is expected to have two +dimensions: c(latitude, longitude). Longitudes can be in ascending or +descending order and latitudes in any order. It can contain NA values +(coloured with 'colNA'). Arrays with dimensions c(longitude, latitude) +will also be accepted but 'lon' and 'lat' will be used to disambiguate so +this alternative is not appropriate for square arrays.} + +\item{lon}{Numeric vector of longitude locations of the cell centers of the +grid of 'var', in ascending or descending order (same as 'var'). Expected +to be regularly spaced, within either of the ranges [-180, 180] or +[0, 360]. Data for two adjacent regions split by the limits of the +longitude range can also be provided, e.g. \code{lon = c(0:50, 300:360)} +('var' must be provided consitently).} + +\item{lat}{Numeric vector of latitude locations of the cell centers of the +grid of 'var', in any order (same as 'var'). Expected to be from a regular +rectangular or gaussian grid, within the range [-90, 90].} + +\item{varu}{Array of the zonal component of wind/current/other field with +the same dimensions as 'var'.} + +\item{varv}{Array of the meridional component of wind/current/other field +with the same dimensions as 'var'.} + +\item{toptitle}{Top title of the figure, scalable with parameter +'title_scale'.} + +\item{sizetit}{Scale factor for the figure top title provided in parameter +'toptitle'. Deprecated. Use 'title_scale' instead.} + +\item{units}{Title at the top of the colour bar, most commonly the units of +the variable provided in parameter 'var'.} + +\item{brks, cols, bar_limits, triangle_ends}{Usually only providing 'brks' is +enough to generate the desired colour bar. These parameters allow to +define n breaks that define n - 1 intervals to classify each of the values +in 'var'. The corresponding grid cell of a given value in 'var' will be +coloured in function of the interval it belongs to. These parameters are +sent to \code{ColorBar()} to generate the breaks and colours. Additional +colours for values beyond the limits of the colour bar are also generated +and applied to the plot if 'bar_limits' or 'brks' and 'triangle_ends' are +properly provided to do so. See ?ColorBar for a full explanation.} + +\item{col_inf, col_sup, colNA}{Colour identifiers to colour the values in +'var' that go beyond the extremes of the colour bar and to colour NA +values, respectively. 'colNA' takes attr(cols, 'na_color') if available by +default, where cols is the parameter 'cols' if provided or the vector of +colors returned by 'color_fun'. If not available, it takes 'pink' by +default. 'col_inf' and 'col_sup' will take the value of 'colNA' if not +specified. See ?ColorBar for a full explanation on 'col_inf' and 'col_sup'.} + +\item{color_fun, subsampleg, bar_extra_labels, draw_bar_ticks, draw_separators, triangle_ends_scale, bar_label_digits, bar_label_scale, units_scale, bar_tick_scale, bar_extra_margin}{Set of parameters to control the visual +aspect of the drawn colour bar. See ?ColorBar for a full explanation.} + +\item{square}{Logical value to choose either to draw a coloured square for +each grid cell in 'var' (TRUE; default) or to draw contour lines and fill +the spaces in between with colours (FALSE). In the latter case, +'filled.continents' will take the value FALSE if not specified.} + +\item{filled.continents}{Colour to fill in drawn projected continents. +Takes the value gray(0.5) by default or, if 'square = FALSE', takes the +value FALSE. If set to FALSE, continents are not filled in.} + +\item{coast_color}{Colour of the coast line of the drawn projected continents. +Takes the value gray(0.5) by default.} + +\item{coast_width}{Line width of the coast line of the drawn projected +continents. Takes the value 1 by default.} + +\item{contours}{Array of same dimensions as 'var' to be added to the plot +and displayed with contours. Parameter 'brks2' is required to define the +magnitude breaks for each contour curve. Disregarded if 'square = FALSE'.} + +\item{brks2}{Vector of magnitude breaks where to draw contour curves for the +array provided in 'contours' or if 'square = FALSE'.} + +\item{contour_lwd}{Line width of the contour curves provided via 'contours' +and 'brks2', or if 'square = FALSE'.} + +\item{contour_color}{Line color of the contour curves provided via 'contours' +and 'brks2', or if 'square = FALSE'.} + +\item{contour_lty}{Line type of the contour curves. Takes 1 (solid) by +default. See help on 'lty' in par() for other accepted values.} + +\item{contour_label_scale}{Scale factor for the superimposed labels when +drawing contour levels.} + +\item{dots}{Array of same dimensions as 'var' or with dimensions +c(n, dim(var)), where n is the number of dot/symbol layers to add to the +plot. A value of TRUE at a grid cell will draw a dot/symbol on the +corresponding square of the plot. By default all layers provided in 'dots' +are plotted with dots, but a symbol can be specified for each of the +layers via the parameter 'dot_symbol'.} + +\item{dot_symbol}{Single character/number or vector of characters/numbers +that correspond to each of the symbol layers specified in parameter 'dots'. +If a single value is specified, it will be applied to all the layers in +'dots'. Takes 15 (centered square) by default. See 'pch' in par() for +additional accepted options.} + +\item{dot_size}{Scale factor for the dots/symbols to be plotted, specified +in 'dots'. If a single value is specified, it will be applied to all +layers in 'dots'. Takes 1 by default.} + +\item{arr_subsamp}{Subsampling factor to select a subset of arrows in +'varu' and 'varv' to be drawn. Only one out of arr_subsamp arrows will +be drawn. Takes 1 by default.} + +\item{arr_scale}{Scale factor for drawn arrows from 'varu' and 'varv'. +Takes 1 by default.} + +\item{arr_ref_len}{Length of the refence arrow to be drawn as legend at the +bottom of the figure (in same units as 'varu' and 'varv', only affects the +legend for the wind or variable in these arrays). Defaults to 15.} + +\item{arr_units}{Units of 'varu' and 'varv', to be drawn in the legend. +Takes 'm/s' by default.} + +\item{arr_scale_shaft}{Parameter for the scale of the shaft of the arrows +(which also depend on the number of figures and the arr_scale parameter). +Defaults to 1.} + +\item{arr_scale_shaft_angle}{Parameter for the scale of the angle of the +shaft of the arrows (which also depend on the number of figure and the +arr_scale parameter). Defaults to 1.} + +\item{axelab}{Whether to draw longitude and latitude axes or not. +TRUE by default.} + +\item{labW}{Whether to label the longitude axis with a 'W' instead of minus +for negative values. Defaults to FALSE.} + +\item{intylat}{Interval between latitude ticks on y-axis, in degrees. +Defaults to 20.} + +\item{intxlon}{Interval between latitude ticks on x-axis, in degrees. +Defaults to 20.} + +\item{axes_tick_scale}{Scale factor for the tick lines along the longitude +and latitude axes.} + +\item{axes_label_scale}{Scale factor for the labels along the longitude +and latitude axes.} + +\item{drawleg}{Whether to plot a color bar (legend, key) or not. Defaults to +TRUE. It is not possible to plot the colour bar if 'add = TRUE'. Use +ColorBar() and the return values of PlotEquiMap() instead.} + +\item{boxlim}{Limits of a box to be added to the plot, in degrees: +c(x1, y1, x2, y2). A list with multiple box specifications can also be +provided.} + +\item{boxcol}{Colour of the box lines. A vector with a colour for each of +the boxes is also accepted. Defaults to 'purple2'.} + +\item{boxlwd}{Line width of the box lines. A vector with a line width for +each of the boxes is also accepted. Defaults to 5.} + +\item{margin_scale}{Scale factor for the margins around the map plot, with +the format c(y1, x1, y2, x2). Defaults to rep(1, 4). If drawleg = TRUE, +then margin_scale[1] is subtracted 1 unit.} + +\item{title_scale}{Scale factor for the figure top title. Defaults to 1.} + +\item{numbfig}{Number of figures in the layout the plot will be put into. +A higher numbfig will result in narrower margins and smaller labels, +axe labels, ticks, thinner lines, ... Defaults to 1.} + +\item{fileout}{File where to save the plot. If not specified (default) a +graphics device will pop up. Extensions allowed: eps/ps, jpeg, png, pdf, +bmp and tiff.} + +\item{width}{File width, in the units specified in the parameter size_units +(inches by default). Takes 8 by default.} + +\item{height}{File height, in the units specified in the parameter +size_units (inches by default). Takes 5 by default.} + +\item{size_units}{Units of the size of the device (file or window) to plot +in. Inches ('in') by default. See ?Devices and the creator function of +the corresponding device.} + +\item{res}{Resolution of the device (file or window) to plot in. See +?Devices and the creator function of the corresponding device.} + +\item{\dots}{Arguments to be passed to the method. Only accepts the following +graphical parameters:\cr +adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt +csi cxy err family fg font font.axis font.lab font.main font.sub lend +lheight ljoin lmitre mex mfcol mfrow mfg mkh omd omi page pch pin plt +pty smo srt tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog \cr +For more information about the parameters see `par`.} } \value{ - \item{brks}{ -Breaks used for colouring the map (and legend if drawleg = TRUE). - } - \item{cols}{ -Colours used for colouring the map (and legend if drawleg = TRUE). Always of length length(brks) - 1. - } - \item{col_inf}{ -Colour used to draw the lower triangle end in the colour bar (NULL if not drawn at all). - } - \item{col_sup}{ -Colour used to draw the upper triangle end in the colour bar (NULL if not drawn at all). - } +\item{brks}{ + Breaks used for colouring the map (and legend if drawleg = TRUE). +} +\item{cols}{ + Colours used for colouring the map (and legend if drawleg = TRUE). Always + of length length(brks) - 1. +} +\item{col_inf}{ + Colour used to draw the lower triangle end in the colour bar (NULL if not + drawn at all). +} +\item{col_sup}{ + Colour used to draw the upper triangle end in the colour bar (NULL if not + drawn at all). +} +} +\description{ +Map longitude-latitude array (on a regular rectangular or gaussian grid) +on a cylindrical equidistant latitude and longitude projection with coloured +grid cells. Only the region for which data has been provided is displayed. +A colour bar (legend) can be plotted and adjusted. It is possible to draw +superimposed arrows, dots, symbols, contour lines and boxes. A number of +options is provided to adjust the position, size and colour of the +components. This plot function is compatible with figure layouts if colour +bar is disabled. } \examples{ # See examples on Load() to understand the first lines in this example - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') expA <- list(name = 'experiment', path = file.path(data_path, - 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', - '$VAR_NAME$_$START_DATE$.nc')) + 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', + '$VAR_NAME$_$START_DATE$.nc')) obsX <- list(name = 'observation', path = file.path(data_path, - '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', - '$VAR_NAME$_$YEAR$$MONTH$.nc')) + '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', + '$VAR_NAME$_$YEAR$$MONTH$.nc')) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(expA), list(obsX), startDates, - leadtimemin = 1, leadtimemax = 4, output = 'lonlat', - latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) - } - \dontshow{ + leadtimemin = 1, leadtimemax = 4, output = 'lonlat', + latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) + } + \dontshow{ startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - leadtimemin = 1, - leadtimemax = 4, - output = 'lonlat', - latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } + c('observation'), startDates, + leadtimemin = 1, + leadtimemax = 4, + output = 'lonlat', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } PlotEquiMap(sampleData$mod[1, 1, 1, 1, , ], sampleData$lon, sampleData$lat, - toptitle = 'Predicted sea surface temperature for Nov 1960 from 1st Nov', - sizetit = 0.5) + toptitle = 'Predicted sea surface temperature for Nov 1960 from 1st Nov', + sizetit = 0.5) } \author{ - History: - 0.1 - 2011-11 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code - 0.2 - 2013-04 (R. Saurral \email{ramiro.saurral@ic3.cat}) - LabW - 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to R CRAN - 1.1 - 2013-09 (C. Prodhomme, \email{chloe.prodhomme@ic3.cat}) - add winds - 1.2 - 2016-08 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Refactored and added features, +History:\cr + 0.1 - 2011-11 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr + 0.2 - 2013-04 (R. Saurral \email{ramiro.saurral@ic3.cat}) - LabW\cr + 1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to R CRAN\cr + 1.1 - 2013-09 (C. Prodhomme, \email{chloe.prodhomme@ic3.cat}) - add winds\cr + 1.2 - 2016-08 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Refactored and added features, and adapted to new ColorBar. } \keyword{dynamic} + diff --git a/man/PlotLayout.Rd b/man/PlotLayout.Rd index 34331a3776bb2eddc5179e7c06abaa3d7f85afe0..e4cf4ecfd7edd11be269ccd363618247b03ddf2e 100644 --- a/man/PlotLayout.Rd +++ b/man/PlotLayout.Rd @@ -1,180 +1,252 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/PlotLayout.R \name{PlotLayout} \alias{PlotLayout} -\title{ -Arrange and Fill Multi-Pannel Layouts With Optional Colour Bar -} -\description{ -This function takes an array or list of arrays and loops over each of them to plot all the sub-arrays they contain on an automatically generated multi-pannel layout. A different plot function (not necessarily from s2dverification) can be applied over each of the provided arrays. The input dimensions of each of the functions have to be specified, either with the names or the indices of the corresponding input dimensions. It is possible to draw a common colour bar at any of the sides of the multi-pannel for all the s2dverification plots that use a colour bar. Common plotting arguments for all the arrays in 'var' can be specified via the '...' parameter, and specific plotting arguments for each array can be fully adjusted via 'special_args'. It is possible to draw titles for each of the figures, layout rows, layout columns and for the whole figure. A number of parameters is provided in order to adjust the position, size and colour of the components. Blank cells can be forced to appear and later be filled in manually with customized plots. -This function pops up a blank new device and fills it in, so it cannot be nested in complex layouts. -} +\title{Arrange and Fill Multi-Pannel Layouts With Optional Colour Bar} \usage{ -PlotLayout(fun, plot_dims, var, ..., special_args = NULL, - nrow = NULL, ncol = NULL, toptitle = NULL, - row_titles = NULL, col_titles = NULL, bar_scale = 1, - title_scale = 1, title_margin_scale = 1, - title_left_shift_scale = 1, - subtitle_scale = 1, subtitle_margin_scale = 1, - brks = NULL, cols = NULL, drawleg = 'S', titles = NULL, - subsampleg = NULL, bar_limits = NULL, - triangle_ends = NULL, col_inf = NULL, col_sup = NULL, - color_fun = clim.colors, - draw_bar_ticks = TRUE, draw_separators = FALSE, - triangle_ends_scale = 1, bar_extra_labels = NULL, - units = NULL, units_scale = 1, bar_label_scale = 1, - bar_tick_scale = 1, bar_extra_margin = rep(0, 4), - bar_left_shift_scale = 1, bar_label_digits = 4, - extra_margin = rep(0, 4), - fileout = NULL, width = NULL, height = NULL, - size_units = 'in', res = 100, close_device = TRUE) +PlotLayout(fun, plot_dims, var, ..., special_args = NULL, nrow = NULL, + ncol = NULL, toptitle = NULL, row_titles = NULL, col_titles = NULL, + bar_scale = 1, title_scale = 1, title_margin_scale = 1, + title_left_shift_scale = 1, subtitle_scale = 1, + subtitle_margin_scale = 1, brks = NULL, cols = NULL, drawleg = "S", + titles = NULL, subsampleg = NULL, bar_limits = NULL, + triangle_ends = NULL, col_inf = NULL, col_sup = NULL, + color_fun = clim.colors, draw_bar_ticks = TRUE, draw_separators = FALSE, + triangle_ends_scale = 1, bar_extra_labels = NULL, units = NULL, + units_scale = 1, bar_label_scale = 1, bar_tick_scale = 1, + bar_extra_margin = rep(0, 4), bar_left_shift_scale = 1, + bar_label_digits = 4, extra_margin = rep(0, 4), fileout = NULL, + width = NULL, height = NULL, size_units = "in", res = 100, + close_device = TRUE) } \arguments{ - \item{fun}{ -Plot function (or name of the function) to be called on the arrays provided in 'var'. If multiple arrays are provided in 'var', a vector of as many function names (character strings!) can be provided in 'fun', one for each array in 'var'. - } - \item{plot_dims}{ -Numeric or character string vector with identifiers of the input plot dimensions of the plot function specified in 'fun'. If character labels are provided, names(dim(var)) or attr('dimensions', var) will be checked to locate the dimensions. As many plots as prod(dim(var)[-plot_dims]) will be generated. If multiple arrays are provided in 'var', 'plot_dims' can be sent a list with a vector of plot dimensions for each. If a single vector is provided, it will be used for all the arrays in 'var'. - } - \item{var}{ -Multi-dimensional array with at least the dimensions expected by the specified plot function in 'fun'. The dimensions reqired by the function must be specified in 'plot_dims'. The dimensions can be disordered and will be reordered automatically. Dimensions can optionally be labelled in order to refer to them with names in 'plot_dims'. All the available plottable sub-arrays will be automatically plotted and arranged in consecutive cells of an automatically arranged layout. A list of multiple (super-)arrays can be specified. The process will be repeated for each of them, by default applying the same plot function to all of them or, if properly specified in 'fun', a different plot function will be applied to each of them. NAs can be passed to the list: a NA will yield a blank cell in the layout, which can be populated after (see .SwitchToFigure). - } - \item{\dots}{ -Parameters to be sent to the plotting function 'fun'. If multiple arrays are provided in 'var' and multiple functions are provided in 'fun', the parameters provided through \dots will be sent to all the plot functions, as common parameters. To specify concrete arguments for each of the plot functions see parameter 'special_args'. - } - \item{special_args}{ -List of sub-lists, each sub-list having specific extra arguments for each of the plot functions provided in 'fun'. If you want to fix a different value for each plot in the layout you can do so by a) splitting your array into a list of sub-arrays (each with the data for one plot) and providing it as parameter 'var', b) providing a list of named sub-lists in 'special_args', where the names of each sub-list match the names of the parameters to be adjusted, and each value in a sub-list contains the value of the corresponding parameter. - } - \item{nrow}{ -Numeric value to force the number of rows in the automatically generated layout. If higher than the required, this will yield blank cells in the layout (which can then be populated). If lower than the required the function will stop. By default it is configured to arrange the layout in a shape as square as possible. Blank cells can be manually populated after with customized plots (see SwitchTofigure). - } - \item{ncol}{ -Numeric value to force the number of columns in the automatically generated layout. If higher than the required, this will yield blank cells in the layout (which can then be populated). If lower than the required the function will stop. By default it is configured to arrange the layout in a shape as square as possible. Blank cells can be manually populated after with customized plots (see SwitchTofigure). - } - \item{toptitle}{ -Topt title for the multi-pannel. Blank by default. - } - \item{row_titles}{ -Character string vector with titles for each of the rows in the layout. Blank by default. - } - \item{col_titles}{ -Character string vector with titles for each of the columns in the layout. Blank by default. - } - \item{bar_scale}{ -Scale factor for the common colour bar. Takes 1 by default. - } - \item{title_scale}{ -Scale factor for the multi-pannel title. Takes 1 by default. - } - \item{title_margin_scale}{ -Scale factor for the margins surrounding the top title. Takes 1 by default. - } - \item{title_left_shift_scale}{ -When plotting row titles, a shift is added to the horizontal positioning of the top title in order to center it to the region of the figures (without taking row titles into account). This shift can be reduced. A value of 0 will remove the shift completely, centering the title to the total width of the device. This parameter will be disregarded if no 'row_titles' are provided. - } - \item{subtitle_scale}{ -Scale factor for the row titles and column titles (specified in 'row_titles' and 'col_titles'). Takes 1 by default. - } - \item{subtitle_margin_scale}{ -Scale factor for the margins surrounding the subtitles. Takes 1 by default. - } - \item{units}{ -Title at the top of the colour bar, most commonly the units of the variable provided in parameter 'var'. - } - \item{brks,cols,bar_limits,triangle_ends}{ -Usually only providing 'brks' is enough to generate the desired colour bar. These parameters allow to define n breaks that define n - 1 intervals to classify each of the values in 'var'. The corresponding grid cell of a given value in 'var' will be coloured in function of the interval it belongs to. These parameters are sent to \code{ColorBar()} to generate the breaks and colours. Additional colours for values beyond the limits of the colour bar are also generated and applied to the plot if 'bar_limits' or 'brks' and 'triangle_ends' are properly provided to do so. See ?ColorBar for a full explanation.\cr - } - \item{col_inf,col_sup}{ -Colour identifiers to colour the values in 'var' that go beyond the extremes of the colour bar and to colour NA values, respectively. 'colNA' takes 'white' by default. 'col_inf' and 'col_sup' will take the value of 'colNA' if not specified. See ?ColorBar for a full explanation on 'col_inf' and 'col_sup'. - } - \item{color_fun,subsampleg,bar_extra_labels,draw_bar_ticks,draw_separators,triangle_ends_scale,bar_label_digits,bar_label_scale,units_scale,bar_tick_scale,bar_extra_margin}{ -Set of parameters to control the visual aspect of the drawn colour bar. See ?ColorBar for a full explanation. - } - \item{drawleg}{ -Where to draw the common colour bar. Can take values TRUE, FALSE or:\cr - 'up', 'u', 'U', 'top', 't', 'T', 'north', 'n', 'N'\cr - 'down', 'd', 'D', 'bottom', 'b', 'B', 'south', 's', 'S' (default)\cr - 'right', 'r', 'R', 'east', 'e', 'E'\cr - 'left', 'l', 'L', 'west', 'w', 'W' - } - \item{titles}{ -Character string vector with titles for each of the figures in the multi-pannel, from top-left to bottom-right. Blank by default. - } - \item{bar_left_shift_scale}{ -When plotting row titles, a shift is added to the horizontal positioning of the colour bar in order to center it to the region of the figures (without taking row titles into account). This shift can be reduced. A value of 0 will remove the shift completely, centering the colour bar to the total width of the device. This parameter will be disregarded if no 'row_titles' are provided. - } - \item{extra_margin}{ -Extra margins to be added around the layout, in the format c(y1, x1, y2, x2). The units are margin lines. Takes rep(0, 4) by default. - } - \item{fileout}{ -File where to save the plot. If not specified (default) a graphics device will pop up. Extensions allowed: eps/ps, jpeg, png, pdf, bmp and tiff. \cr - } - \item{width}{ -Width in inches of the multi-pannel. 7 by default, or 11 if 'fielout' has been specified. - } - \item{height}{ -Height in inches of the multi-pannel. 7 by default, or 11 if 'fileout' has been specified. - } - \item{size_units}{ -Units of the size of the device (file or window) to plot in. Inches ('in') by default. See ?Devices and the creator function of the corresponding device. - } - \item{res}{ -Resolution of the device (file or window) to plot in. See ?Devices and the creator function of the corresponding device. - } - \item{close_device}{ -Whether to close the graphics device after plotting the layout and a 'fileout' has been specified. This is useful to avoid closing the device when saving the layout into a file and willing to add extra elements or figures. Takes TRUE by default. Disregarded if no 'fileout' has been specified. - } +\item{fun}{Plot function (or name of the function) to be called on the +arrays provided in 'var'. If multiple arrays are provided in 'var', a +vector of as many function names (character strings!) can be provided in +'fun', one for each array in 'var'.} + +\item{plot_dims}{Numeric or character string vector with identifiers of the +input plot dimensions of the plot function specified in 'fun'. If +character labels are provided, names(dim(var)) or attr('dimensions', var) +will be checked to locate the dimensions. As many plots as +prod(dim(var)[-plot_dims]) will be generated. If multiple arrays are +provided in 'var', 'plot_dims' can be sent a list with a vector of plot +dimensions for each. If a single vector is provided, it will be used for +all the arrays in 'var'.} + +\item{var}{Multi-dimensional array with at least the dimensions expected by +the specified plot function in 'fun'. The dimensions reqired by the +function must be specified in 'plot_dims'. The dimensions can be +disordered and will be reordered automatically. Dimensions can optionally +be labelled in order to refer to them with names in 'plot_dims'. All the +available plottable sub-arrays will be automatically plotted and arranged +in consecutive cells of an automatically arranged layout. A list of +multiple (super-)arrays can be specified. The process will be repeated for +each of them, by default applying the same plot function to all of them +or, if properly specified in 'fun', a different plot function will be +applied to each of them. NAs can be passed to the list: a NA will yield a +blank cell in the layout, which can be populated after +(see .SwitchToFigure).} + +\item{special_args}{List of sub-lists, each sub-list having specific extra +arguments for each of the plot functions provided in 'fun'. If you want to +fix a different value for each plot in the layout you can do so by +a) splitting your array into a list of sub-arrays (each with the data for +one plot) and providing it as parameter 'var', +b) providing a list of named sub-lists in 'special_args', where the names +of each sub-list match the names of the parameters to be adjusted, and +each value in a sub-list contains the value of the corresponding parameter.} + +\item{nrow}{Numeric value to force the number of rows in the automatically +generated layout. If higher than the required, this will yield blank cells +in the layout (which can then be populated). If lower than the required +the function will stop. By default it is configured to arrange the layout +in a shape as square as possible. Blank cells can be manually populated +after with customized plots (see SwitchTofigure).} + +\item{ncol}{Numeric value to force the number of columns in the +automatically generated layout. If higher than the required, this will +yield blank cells in the layout (which can then be populated). If lower +than the required the function will stop. By default it is configured to +arrange the layout in a shape as square as possible. Blank cells can be +manually populated after with customized plots (see SwitchTofigure).} + +\item{toptitle}{Topt title for the multi-pannel. Blank by default.} + +\item{row_titles}{Character string vector with titles for each of the rows +in the layout. Blank by default.} + +\item{col_titles}{Character string vector with titles for each of the +columns in the layout. Blank by default.} + +\item{bar_scale}{Scale factor for the common colour bar. Takes 1 by default.} + +\item{title_scale}{Scale factor for the multi-pannel title. Takes 1 by +default.} + +\item{title_margin_scale}{Scale factor for the margins surrounding the top +title. Takes 1 by default.} + +\item{title_left_shift_scale}{When plotting row titles, a shift is added +to the horizontal positioning of the top title in order to center it to +the region of the figures (without taking row titles into account). This +shift can be reduced. A value of 0 will remove the shift completely, +centering the title to the total width of the device. This parameter will +be disregarded if no 'row_titles' are provided.} + +\item{subtitle_scale}{Scale factor for the row titles and column titles +(specified in 'row_titles' and 'col_titles'). Takes 1 by default.} + +\item{subtitle_margin_scale}{Scale factor for the margins surrounding the +subtitles. Takes 1 by default.} + +\item{brks, cols, bar_limits, triangle_ends}{Usually only providing 'brks' is +enough to generate the desired colour bar. These parameters allow to +define n breaks that define n - 1 intervals to classify each of the values +in 'var'. The corresponding grid cell of a given value in 'var' will be +coloured in function of the interval it belongs to. These parameters are +sent to \code{ColorBar()} to generate the breaks and colours. Additional +colours for values beyond the limits of the colour bar are also generated +and applied to the plot if 'bar_limits' or 'brks' and 'triangle_ends' are +properly provided to do so. See ?ColorBar for a full explanation.} + +\item{drawleg}{Where to draw the common colour bar. Can take values TRUE, +FALSE or:\cr +'up', 'u', 'U', 'top', 't', 'T', 'north', 'n', 'N'\cr +'down', 'd', 'D', 'bottom', 'b', 'B', 'south', 's', 'S' (default)\cr +'right', 'r', 'R', 'east', 'e', 'E'\cr +'left', 'l', 'L', 'west', 'w', 'W'} + +\item{titles}{Character string vector with titles for each of the figures in +the multi-pannel, from top-left to bottom-right. Blank by default.} + +\item{col_inf, col_sup}{Colour identifiers to colour the values in 'var' that +go beyond the extremes of the colour bar and to colour NA values, +respectively. 'colNA' takes 'white' by default. 'col_inf' and 'col_sup' +will take the value of 'colNA' if not specified. See ?ColorBar for a full +explanation on 'col_inf' and 'col_sup'.} + +\item{color_fun, subsampleg, bar_extra_labels, draw_bar_ticks, draw_separators, triangle_ends_scale, bar_label_digits, bar_label_scale, units_scale, bar_tick_scale, bar_extra_margin}{Set of parameters to control the visual aspect of the drawn colour bar. See ?ColorBar for a full explanation.} + +\item{units}{Title at the top of the colour bar, most commonly the units of +the variable provided in parameter 'var'.} + +\item{bar_left_shift_scale}{When plotting row titles, a shift is added to +the horizontal positioning of the colour bar in order to center it to the +region of the figures (without taking row titles into account). This shift +can be reduced. A value of 0 will remove the shift completely, centering +the colour bar to the total width of the device. This parameter will be +disregarded if no 'row_titles' are provided.} + +\item{extra_margin}{Extra margins to be added around the layout, in the +format c(y1, x1, y2, x2). The units are margin lines. Takes rep(0, 4) +by default.} + +\item{fileout}{File where to save the plot. If not specified (default) a +graphics device will pop up. Extensions allowed: eps/ps, jpeg, png, pdf, +bmp and tiff.} + +\item{width}{Width in inches of the multi-pannel. 7 by default, or 11 if +'fielout' has been specified.} + +\item{height}{Height in inches of the multi-pannel. 7 by default, or 11 if +'fileout' has been specified.} + +\item{size_units}{Units of the size of the device (file or window) to plot +in. Inches ('in') by default. See ?Devices and the creator function of +the corresponding device.} + +\item{res}{Resolution of the device (file or window) to plot in. See +?Devices and the creator function of the corresponding device.} + +\item{close_device}{Whether to close the graphics device after plotting +the layout and a 'fileout' has been specified. This is useful to avoid +closing the device when saving the layout into a file and willing to add +extra elements or figures. Takes TRUE by default. Disregarded if no +'fileout' has been specified.} + +\item{\dots}{Parameters to be sent to the plotting function 'fun'. If +multiple arrays are provided in 'var' and multiple functions are provided +in 'fun', the parameters provided through \dots will be sent to all the +plot functions, as common parameters. To specify concrete arguments for +each of the plot functions see parameter 'special_args'.} } \value{ - \item{brks}{ -Breaks used for colouring the map (and legend if drawleg = TRUE). - } - \item{cols}{ -Colours used for colouring the map (and legend if drawleg = TRUE). Always of length length(brks) - 1. - } - \item{col_inf}{ -Colour used to draw the lower triangle end in the colour bar (NULL if not drawn at all). - } - \item{col_sup}{ -Colour used to draw the upper triangle end in the colour bar (NULL if not drawn at all). - } - \item{layout_matrix}{ -Underlying matrix of the layout. Useful to later set any of the layout cells as current figure to add plot elements. See .SwitchToFigure. - } +\item{brks}{ + Breaks used for colouring the map (and legend if drawleg = TRUE). +} +\item{cols}{ + Colours used for colouring the map (and legend if drawleg = TRUE). + Always of length length(brks) - 1. +} +\item{col_inf}{ + Colour used to draw the lower triangle end in the colour bar + (NULL if not drawn at all). +} +\item{col_sup}{ + Colour used to draw the upper triangle end in the colour bar + (NULL if not drawn at all). +} +\item{layout_matrix}{ + Underlying matrix of the layout. Useful to later set any of the layout + cells as current figure to add plot elements. See .SwitchToFigure. +} +} +\description{ +This function takes an array or list of arrays and loops over each of them +to plot all the sub-arrays they contain on an automatically generated +multi-pannel layout. A different plot function (not necessarily from +s2dverification) can be applied over each of the provided arrays. The input +dimensions of each of the functions have to be specified, either with the +names or the indices of the corresponding input dimensions. It is possible +to draw a common colour bar at any of the sides of the multi-pannel for all +the s2dverification plots that use a colour bar. Common plotting arguments +for all the arrays in 'var' can be specified via the '...' parameter, and +specific plotting arguments for each array can be fully adjusted via +'special_args'. It is possible to draw titles for each of the figures, +layout rows, layout columns and for the whole figure. A number of parameters +is provided in order to adjust the position, size and colour of the +components. Blank cells can be forced to appear and later be filled in +manually with customized plots.\cr +This function pops up a blank new device and fills it in, so it cannot be +nested in complex layouts. } \examples{ # See examples on Load() to understand the first lines in this example - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') expA <- list(name = 'experiment', path = file.path(data_path, - 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', - '$VAR_NAME$_$START_DATE$.nc')) + 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', + '$VAR_NAME$_$START_DATE$.nc')) obsX <- list(name = 'observation', path = file.path(data_path, - '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', - '$VAR_NAME$_$YEAR$$MONTH$.nc')) + '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', + '$VAR_NAME$_$YEAR$$MONTH$.nc')) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(expA), list(obsX), startDates, - leadtimemin = 1, leadtimemax = 4, output = 'lonlat', - latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) - } - \dontshow{ + leadtimemin = 1, leadtimemax = 4, output = 'lonlat', + latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) + } + \dontshow{ startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - leadtimemin = 1, - leadtimemax = 4, - output = 'lonlat', - latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } + c('observation'), startDates, + leadtimemin = 1, + leadtimemax = 4, + output = 'lonlat', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } PlotLayout(PlotEquiMap, c('lat', 'lon'), sampleData$mod[1, , 1, 1, , ], - sampleData$lon, sampleData$lat, - toptitle = 'Predicted tos for Nov 1960 from 1st Nov', - titles = paste('Member', 1:15)) + sampleData$lon, sampleData$lat, + toptitle = 'Predicted tos for Nov 1960 from 1st Nov', + titles = paste('Member', 1:15)) + } \author{ - History: - 0.1 - 2016-08 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Original code +History:\cr + 0.1 - 2016-08 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Original code } \keyword{dynamic} diff --git a/man/PlotSection.Rd b/man/PlotSection.Rd index f7f3349f9e0d2e58e108edeb5d30229593e863ba..f74473190242d1630ab85d8b0e7b0fdbefc387e5 100644 --- a/man/PlotSection.Rd +++ b/man/PlotSection.Rd @@ -1,89 +1,78 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/PlotSection.R \name{PlotSection} \alias{PlotSection} -\title{ -Plots A Vertical Section -} -\description{ -Plot a (longitude,depth) or (latitude,depth) section. -} +\title{Plots A Vertical Section} \usage{ -PlotSection(var, horiz, depth, toptitle = "", sizetit = 1, units = "", - brks = NULL, cols = NULL, axelab = TRUE, intydep = 200, - intxhoriz = 20, drawleg = TRUE, fileout = NULL, - width = 8, height = 5, size_units = 'in', res = 100, ...) +PlotSection(var, horiz, depth, toptitle = "", sizetit = 1, units = "", + brks = NULL, cols = NULL, axelab = TRUE, intydep = 200, + intxhoriz = 20, drawleg = TRUE, fileout = NULL, width = 8, + height = 5, size_units = "in", res = 100, ...) } \arguments{ - \item{var}{ -Matrix to plot with (longitude/latitude, depth) dimensions. - } - \item{horiz}{ -Array of longitudes or latitudes. - } - \item{depth}{ -Array of depths. - } - \item{toptitle}{ -Title, optional. - } - \item{sizetit}{ -Multiplicative factor to increase title size, optional. - } - \item{units}{ -Units, optional. - } - \item{brks}{ -Colour levels, optional. - } - \item{cols}{ -List of colours, optional. - } - \item{axelab}{ -TRUE/FALSE, label the axis. Default = TRUE. - } - \item{intydep}{ -Interval between depth ticks on y-axis. Default: 200m. - } - \item{intxhoriz}{ -Interval between longitude/latitude ticks on x-axis.\cr -Default: 20deg. - } - \item{drawleg}{ -Draw colorbar. Default: TRUE. - } - \item{width}{ -File width, in the units specified in the parameter size_units (inches by default). Takes 8 by default. - } - \item{height}{ -File height, in the units specified in the parameter size_units (inches by default). Takes 5 by default. - } - \item{size_units}{ -Units of the size of the device (file or window) to plot in. Inches ('in') by default. See ?Devices and the creator function of the corresponding device. - } - \item{res}{ -Resolution of the device (file or window) to plot in. See ?Devices and the creator function of the corresponding device. - } - \item{fileout}{ -Name of output file. Extensions allowed: eps/ps, jpeg, png, pdf, bmp -and tiff. \cr -Default = NULL - } - \item{...}{ - Arguments to be passed to the method. Only accepts the following - graphical parameters: - - adj ann ask bg bty cex.lab cex.sub cin col.axis col.lab col.main col.sub cra crt csi cxy err family fg fig fin font font.axis font.lab font.main font.sub lend lheight ljoin lmitre lty lwd mex mfcol mfrow mfg mkh oma omd omi page pch pin plt pty smo srt tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog - - For more information about the parameters see `par` - } +\item{var}{Matrix to plot with (longitude/latitude, depth) dimensions.} + +\item{horiz}{Array of longitudes or latitudes.} + +\item{depth}{Array of depths.} + +\item{toptitle}{Title, optional.} + +\item{sizetit}{Multiplicative factor to increase title size, optional.} + +\item{units}{Units, optional.} + +\item{brks}{Colour levels, optional.} + +\item{cols}{List of colours, optional.} + +\item{axelab}{TRUE/FALSE, label the axis. Default = TRUE.} + +\item{intydep}{Interval between depth ticks on y-axis. Default: 200m.} + +\item{intxhoriz}{Interval between longitude/latitude ticks on x-axis.\cr +Default: 20deg.} + +\item{drawleg}{Draw colorbar. Default: TRUE.} + +\item{fileout}{Name of output file. Extensions allowed: eps/ps, jpeg, png, +pdf, bmp and tiff. \cr +Default = NULL} + +\item{width}{File width, in the units specified in the parameter size_units +(inches by default). Takes 8 by default.} + +\item{height}{File height, in the units specified in the parameter +size_units (inches by default). Takes 5 by default.} + +\item{size_units}{Units of the size of the device (file or window) to plot +in. Inches ('in') by default. See ?Devices and the creator function of the +corresponding device.} + +\item{res}{Resolution of the device (file or window) to plot in. See +?Devices and the creator function of the corresponding device.} + +\item{...}{Arguments to be passed to the method. Only accepts the following +graphical parameters:\cr +adj ann ask bg bty cex.lab cex.sub cin col.axis col.lab col.main col.sub +cra crt csi cxy err family fg fig fin font font.axis font.lab font.main +font.sub lend lheight ljoin lmitre lty lwd mex mfcol mfrow mfg mkh oma omd +omi page pch pin plt pty smo srt tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs +yaxt ylbias ylog \cr +For more information about the parameters see `par`.} +} +\description{ +Plot a (longitude,depth) or (latitude,depth) section. } \examples{ sampleData <- s2dverification::sampleDepthData PlotSection(sampleData$mod[1, 1, 1, 1, , ], sampleData$lat, sampleData$depth, - toptitle = 'temperature 1995-11 member 0') + toptitle = 'temperature 1995-11 member 0') } \author{ History:\cr -0.1 - 2012-09 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +0.1 - 2012-09 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{dynamic} + diff --git a/man/PlotStereoMap.Rd b/man/PlotStereoMap.Rd index 8b262b7f61654c85d9a6b3d19b19118efacacda3..3bf2f69c44f509a9afbbcb34f6fa9f9dfcc0d198 100644 --- a/man/PlotStereoMap.Rd +++ b/man/PlotStereoMap.Rd @@ -1,157 +1,195 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/PlotStereoMap.R \name{PlotStereoMap} \alias{PlotStereoMap} -\title{ -Maps A Two-Dimensional Variable On A Polar Stereographic Projection -} -\description{ -Map longitude-latitude array (on a regular rectangular or gaussian grid) on a polar stereographic world projection with coloured grid cells. Only the region within a specified latitude interval is displayed. A colour bar (legend) can be plotted and adjusted. It is possible to draw superimposed dots, symbols and boxes. A number of options is provided to adjust the position, size and colour of the components. This plot function is compatible with figure layouts if colour bar is disabled.. -} +\title{Maps A Two-Dimensional Variable On A Polar Stereographic Projection} \usage{ -PlotStereoMap(var, lon, lat, latlims = c(60, 90), - toptitle = NULL, sizetit = NULL, units = NULL, - brks = NULL, cols = NULL, bar_limits = NULL, - triangle_ends = NULL, col_inf = NULL, col_sup = NULL, - colNA = NULL, color_fun = clim.palette(), - filled.continents = FALSE, coast_color = NULL, - coast_width = 1, - dots = NULL, dot_symbol = 4, dot_size = 0.8, - intlat = 10, - drawleg = TRUE, subsampleg = NULL, - bar_extra_labels = NULL, draw_bar_ticks = TRUE, - draw_separators = FALSE, triangle_ends_scale = 1, - bar_label_digits = 4, bar_label_scale = 1, - units_scale = 1, bar_tick_scale = 1, - bar_extra_margin = rep(0, 4), - boxlim = NULL, boxcol = "purple2", boxlwd = 5, - margin_scale = rep(1, 4), title_scale = 1, - numbfig = NULL, fileout = NULL, width = 6, height = 5, - size_units = 'in', res = 100, ...) +PlotStereoMap(var, lon, lat, latlims = c(60, 90), toptitle = NULL, + sizetit = NULL, units = NULL, brks = NULL, cols = NULL, + bar_limits = NULL, triangle_ends = NULL, col_inf = NULL, + col_sup = NULL, colNA = NULL, color_fun = clim.palette(), + filled.continents = FALSE, coast_color = NULL, coast_width = 1, + dots = NULL, dot_symbol = 4, dot_size = 0.8, intlat = 10, + drawleg = TRUE, subsampleg = NULL, bar_extra_labels = NULL, + draw_bar_ticks = TRUE, draw_separators = FALSE, triangle_ends_scale = 1, + bar_label_digits = 4, bar_label_scale = 1, units_scale = 1, + bar_tick_scale = 1, bar_extra_margin = rep(0, 4), boxlim = NULL, + boxcol = "purple2", boxlwd = 5, margin_scale = rep(1, 4), + title_scale = 1, numbfig = NULL, fileout = NULL, width = 6, + height = 5, size_units = "in", res = 100, ...) } \arguments{ - \item{var}{ -Array with the values at each cell of a grid on a regular rectangular or gaussian grid. The array is expected to have two dimensions: c(latitude, longitude). Longitudes can be in ascending or descending order and latitudes in any order. It can contain NA values (coloured with 'colNA'). Arrays with dimensions c(longitude, latitude) will also be accepted but 'lon' and 'lat' will be used to disambiguate so this alternative is not appropriate for square arrays. - } - \item{lon}{ -Numeric vector of longitude locations of the cell centers of the grid of 'var', in ascending or descending order (same as 'var'). Expected to be regularly spaced, within either of the ranges [-180, 180] or [0, 360]. Data for two adjacent regions split by the limits of the longitude range can also be provided, e.g. \code{lon = c(0:50, 300:360)} ('var' must be provided consitently). - } - \item{lat}{ -Numeric vector of latitude locations of the cell centers of the grid of 'var', in any order (same as 'var'). Expected to be from a regular rectangular or gaussian grid, within the range [-90, 90]. - } - \item{latlims}{ -Latitudinal limits of the figure.\cr +\item{var}{Array with the values at each cell of a grid on a regular +rectangular or gaussian grid. The array is expected to have two dimensions: +c(latitude, longitude). Longitudes can be in ascending or descending order +and latitudes in any order. It can contain NA values (coloured with +'colNA'). Arrays with dimensions c(longitude, latitude) will also be +accepted but 'lon' and 'lat' will be used to disambiguate so this +alternative is not appropriate for square arrays.} + +\item{lon}{Numeric vector of longitude locations of the cell centers of the +grid of 'var', in ascending or descending order (same as 'var'). Expected +to be regularly spaced, within either of the ranges [-180, 180] or +[0, 360]. Data for two adjacent regions split by the limits of the +longitude range can also be provided, e.g. \code{lon = c(0:50, 300:360)} +('var' must be provided consitently).} + +\item{lat}{Numeric vector of latitude locations of the cell centers of the +grid of 'var', in any order (same as 'var'). Expected to be from a regular +rectangular or gaussian grid, within the range [-90, 90].} + +\item{latlims}{Latitudinal limits of the figure.\cr Example : c(60, 90) for the North Pole\cr - c(-90,-60) for the South Pole - } - \item{toptitle}{ -Top title of the figure, scalable with parameter 'title_scale'. - } - \item{sizetit}{ -Scale factor for the figure top title provided in parameter 'toptitle'. Deprecated. Use 'title_scale' instead. - } - \item{units}{ -Title at the top of the colour bar, most commonly the units of the variable provided in parameter 'var'. - } - \item{brks,cols,bar_limits,triangle_ends}{ -Usually only providing 'brks' is enough to generate the desired colour bar. These parameters allow to define n breaks that define n - 1 intervals to classify each of the values in 'var'. The corresponding grid cell of a given value in 'var' will be coloured in function of the interval it belongs to. These parameters are sent to \code{ColorBar()} to generate the breaks and colours. Additional colours for values beyond the limits of the colour bar are also generated and applied to the plot if 'bar_limits' or 'brks' and 'triangle_ends' are properly provided to do so. See ?ColorBar for a full explanation.\cr - } - \item{col_inf,col_sup,colNA}{ -Colour identifiers to colour the values in 'var' that go beyond the extremes of the colour bar and to colour NA values, respectively. 'colNA' takes attr(cols, 'na_color') if available by default, where cols is the parameter 'cols' if provided or the vector of colors returned by 'color_fun'. If not available, it takes 'pink' by default. 'col_inf' and 'col_sup' will take the value of 'colNA' if not specified. See ?ColorBar for a full explanation on 'col_inf' and 'col_sup'. - } - \item{color_fun,subsampleg,bar_extra_labels,draw_bar_ticks,draw_separators,triangle_ends_scale,bar_label_digits,bar_label_scale,units_scale,bar_tick_scale,bar_extra_margin}{ -Set of parameters to control the visual aspect of the drawn colour bar. See ?ColorBar for a full explanation. - } - \item{filled.continents}{ -Colour to fill in drawn projected continents. Takes the value gray(0.5) by default. If set to FALSE, continents are not filled in. - } - \item{coast_color}{ -Colour of the coast line of the drawn projected continents. Takes the value gray(0.5) by default. - } - \item{coast_width}{ -Line width of the coast line of the drawn projected continents. Takes the value 1 by default. - } - \item{dots}{ -Array of same dimensions as 'var' or with dimensions c(n, dim(var)), where n is the number of dot/symbol layers to add to the plot. A value of TRUE at a grid cell will draw a dot/symbol on the corresponding square of the plot. By default all layers provided in 'dots' are plotted with dots, but a symbol can be specified for each of the layers via the parameter 'dot_symbol'. - } - \item{dot_symbol}{ -Single character/number or vector of characters/numbers that correspond to each of the symbol layers specified in parameter 'dots'. If a single value is specified, it will be applied to all the layers in 'dots'. Takes 15 (centered square) by default. See 'pch' in par() for additional accepted options. - } - \item{dot_size}{ -Scale factor for the dots/symbols to be plotted, specified in 'dots'. If a single value is specified, it will be applied to all layers in 'dots'. Takes 1 by default. - } - \item{intlat}{ -Interval between latitude lines (circles), in degrees. Defaults to 10. - } - \item{drawleg}{ -Whether to plot a color bar (legend, key) or not. Defaults to TRUE. - } - \item{boxlim}{ -Limits of a box to be added to the plot, in degrees: c(x1, y1, x2, y2). A list with multiple box specifications can also be provided. - } - \item{boxcol}{ -Colour of the box lines. A vector with a colour for each of the boxes is also accepted. Defaults to 'purple2'. - } - \item{boxlwd}{ -Line width of the box lines. A vector with a line width for each of the boxes is also accepted. Defaults to 5. - } - \item{margin_scale}{ -Scale factor for the margins to be added to the plot, with the format c(y1, x1, y2, x2). Defaults to rep(1, 4). If drawleg = TRUE, margin_scale[1] is subtracted 1 unit. - } - \item{title_scale}{ -Scale factor for the figure top title. Defaults to 1. - } - \item{numbfig}{ -Number of figures in the layout the plot will be put into. A higher numbfig will result in narrower margins and smaller labels, axe labels, ticks, thinner lines, ... Defaults to 1. - } - \item{fileout}{ -File where to save the plot. If not specified (default) a graphics device will pop up. Extensions allowed: eps/ps, jpeg, png, pdf, bmp and tiff. \cr - } - \item{width}{ -File width, in the units specified in the parameter size_units (inches by default). Takes 8 by default. - } - \item{height}{ -File height, in the units specified in the parameter size_units (inches by default). Takes 5 by default. - } - \item{size_units}{ -Units of the size of the device (file or window) to plot in. Inches ('in') by default. See ?Devices and the creator function of the corresponding device. - } - \item{res}{ -Resolution of the device (file or window) to plot in. See ?Devices and the creator function of the corresponding device. - } - \item{\dots}{ -Arguments to be passed to the method. Only accepts the following graphical parameters: - -adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt csi cxy err family fg font font.axis font.lab font.main font.sub lend lheight ljoin lmitre mex mfcol mfrow mfg mkh omd omi page pch pin plt pty smo srt tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog - -For more information about the parameters see `par`. - } + c(-90,-60) for the South Pole} + +\item{toptitle}{Top title of the figure, scalable with parameter +'title_scale'.} + +\item{sizetit}{Scale factor for the figure top title provided in parameter +'toptitle'. Deprecated. Use 'title_scale' instead.} + +\item{units}{Title at the top of the colour bar, most commonly the units of +the variable provided in parameter 'var'.} + +\item{brks, cols, bar_limits, triangle_ends}{Usually only providing 'brks' is +enough to generate the desired colour bar. These parameters allow to +define n breaks that define n - 1 intervals to classify each of the values +in 'var'. The corresponding grid cell of a given value in 'var' will be +coloured in function of the interval it belongs to. These parameters are +sent to \code{ColorBar()} to generate the breaks and colours. Additional +colours for values beyond the limits of the colour bar are also generated +and applied to the plot if 'bar_limits' or 'brks' and 'triangle_ends' are +properly provided to do so. See ?ColorBar for a full explanation.} + +\item{col_inf, col_sup, colNA}{Colour identifiers to colour the values in +'var' that go beyond the extremes of the colour bar and to colour NA +values, respectively. 'colNA' takes attr(cols, 'na_color') if available by +default, where cols is the parameter 'cols' if provided or the vector of +colors returned by 'color_fun'. If not available, it takes 'pink' by +default. 'col_inf' and 'col_sup' will take the value of 'colNA' if not +specified. See ?ColorBar for a full explanation on 'col_inf' and 'col_sup'.} + +\item{color_fun, subsampleg, bar_extra_labels, draw_bar_ticks, draw_separators, triangle_ends_scale, bar_label_digits, bar_label_scale, units_scale, bar_tick_scale, bar_extra_margin}{Set of parameters to control the visual +aspect of the drawn colour bar. See ?ColorBar for a full explanation.} + +\item{filled.continents}{Colour to fill in drawn projected continents. Takes +the value gray(0.5) by default. If set to FALSE, continents are not +filled in.} + +\item{coast_color}{Colour of the coast line of the drawn projected +continents. Takes the value gray(0.5) by default.} + +\item{coast_width}{Line width of the coast line of the drawn projected +continents. Takes the value 1 by default.} + +\item{dots}{Array of same dimensions as 'var' or with dimensions +c(n, dim(var)), where n is the number of dot/symbol layers to add to the +plot. A value of TRUE at a grid cell will draw a dot/symbol on the +corresponding square of the plot. By default all layers provided in 'dots' +are plotted with dots, but a symbol can be specified for each of the +layers via the parameter 'dot_symbol'.} + +\item{dot_symbol}{Single character/number or vector of characters/numbers +that correspond to each of the symbol layers specified in parameter 'dots'. +If a single value is specified, it will be applied to all the layers in +'dots'. Takes 15 (centered square) by default. See 'pch' in par() for +additional accepted options.} + +\item{dot_size}{Scale factor for the dots/symbols to be plotted, specified +in 'dots'. If a single value is specified, it will be applied to all +layers in 'dots'. Takes 1 by default.} + +\item{intlat}{Interval between latitude lines (circles), in degrees. +Defaults to 10.} + +\item{drawleg}{Whether to plot a color bar (legend, key) or not. +Defaults to TRUE.} + +\item{boxlim}{Limits of a box to be added to the plot, in degrees: +c(x1, y1, x2, y2). A list with multiple box specifications can also +be provided.} + +\item{boxcol}{Colour of the box lines. A vector with a colour for each of +the boxes is also accepted. Defaults to 'purple2'.} + +\item{boxlwd}{Line width of the box lines. A vector with a line width for +each of the boxes is also accepted. Defaults to 5.} + +\item{margin_scale}{Scale factor for the margins to be added to the plot, +with the format c(y1, x1, y2, x2). Defaults to rep(1, 4). If drawleg = TRUE, +margin_scale[1] is subtracted 1 unit.} + +\item{title_scale}{Scale factor for the figure top title. Defaults to 1.} + +\item{numbfig}{Number of figures in the layout the plot will be put into. +A higher numbfig will result in narrower margins and smaller labels, +axe labels, ticks, thinner lines, ... Defaults to 1.} + +\item{fileout}{File where to save the plot. If not specified (default) a +graphics device will pop up. Extensions allowed: eps/ps, jpeg, png, pdf, +bmp and tiff.} + +\item{width}{File width, in the units specified in the parameter size_units +(inches by default). Takes 8 by default.} + +\item{height}{File height, in the units specified in the parameter +size_units (inches by default). Takes 5 by default.} + +\item{size_units}{Units of the size of the device (file or window) to plot +in. Inches ('in') by default. See ?Devices and the creator function of +the corresponding device.} + +\item{res}{Resolution of the device (file or window) to plot in. See +?Devices and the creator function of the corresponding device.} + +\item{\dots}{Arguments to be passed to the method. Only accepts the +following graphical parameters:\cr +adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt +csi cxy err family fg font font.axis font.lab font.main font.sub lend +lheight ljoin lmitre mex mfcol mfrow mfg mkh omd omi page pch pin plt pty +smo srt tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog \cr +For more information about the parameters see `par`.} } \value{ - \item{brks}{ -Breaks used for colouring the map (and legend if drawleg = TRUE). - } - \item{cols}{ -Colours used for colouring the map (and legend if drawleg = TRUE). Always of length length(brks) - 1. - } - \item{col_inf}{ -Colour used to draw the lower triangle end in the colour bar (NULL if not drawn at all). - } - \item{col_sup}{ -Colour used to draw the upper triangle end in the colour bar (NULL if not drawn at all). - } +\item{brks}{ + Breaks used for colouring the map (and legend if drawleg = TRUE). +} +\item{cols}{ + Colours used for colouring the map (and legend if drawleg = TRUE). Always + of length length(brks) - 1. +} +\item{col_inf}{ + Colour used to draw the lower triangle end in the colour bar (NULL if not + drawn at all). +} +\item{col_sup}{ + Colour used to draw the upper triangle end in the colour bar (NULL if not + drawn at all). +} +} +\description{ +Map longitude-latitude array (on a regular rectangular or gaussian grid) on +a polar stereographic world projection with coloured grid cells. Only the +region within a specified latitude interval is displayed. A colour bar +(legend) can be plotted and adjusted. It is possible to draw superimposed +dots, symbols and boxes. A number of options is provided to adjust the +position, size and colour of the components. This plot function is +compatible with figure layouts if colour bar is disabled. } \examples{ data <- matrix(rnorm(100 * 50), 100, 50) x <- seq(from = 0, to = 360, length.out = 100) y <- seq(from = -90, to = 90, length.out = 50) PlotStereoMap(data, x, y, latlims = c(60, 90), brks = 50, - toptitle = "This is the title") + toptitle = "This is the title") } \author{ History:\cr -1.0 - 2014-07 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code -1.1 - 2015-12 (C. Ardilouze, \email{constantin.ardilouze at meteo.fr}) - Box(es) drawing -1.2 - 2016-08 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Refacotred the function and - merged in Jean-Philippe circle - border and Constantin boxes. +1.0 - 2014-07 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +1.1 - 2015-12 (C. Ardilouze, \email{constantin.ardilouze@meteo.fr}) - Box(es) drawing\cr +1.2 - 2016-08 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Refacotred the function and + merged in Jean-Philippe circle + border and Constantin boxes. } \keyword{dynamic} + diff --git a/man/PlotVsLTime.Rd b/man/PlotVsLTime.Rd index cebb9e50f8b1069e83dfd52898e0cafa504945b2..e908e57b2ce6c8bd8b0810d266316ca9f3e2491b 100644 --- a/man/PlotVsLTime.Rd +++ b/man/PlotVsLTime.Rd @@ -1,107 +1,103 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/PlotVsLTime.R \name{PlotVsLTime} \alias{PlotVsLTime} -\title{ -Plots A Score Along The Forecast Time With Its Confidence Interval -} -\description{ -Plots The Correlation (\code{Corr()}) or the Root Mean Square Error (\code{RMS()}) between the forecasted values and their observational counterpart or the slopes of their trends (\code{Trend()}) or the InterQuartile Range, Maximum-Mininum, Standard Deviation or Median Absolute Deviation of the Ensemble Members (\code{Spread()}), or the ratio between the Ensemble Spread and the RMSE of the Ensemble Mean (\code{RatioSDRMS()}) along the forecast time for all the input experiments on the same figure with their confidence intervals. -} +\title{Plots A Score Along The Forecast Time With Its Confidence Interval} \usage{ -PlotVsLTime(var, toptitle = "", ytitle = "", monini = 1, freq = 12, - nticks = NULL, limits = NULL, listexp = c("exp1", "exp2", "exp3"), - listobs = c("obs1", "obs2", "obs3"), biglab = FALSE, hlines = NULL, - leg = TRUE, siglev = FALSE, sizetit = 1, show_conf = TRUE, - fileout = "output_plotvsltime.eps", - width = 8, height = 5, size_units = 'in', res = 100, ...) +PlotVsLTime(var, toptitle = "", ytitle = "", monini = 1, freq = 12, + nticks = NULL, limits = NULL, listexp = c("exp1", "exp2", "exp3"), + listobs = c("obs1", "obs2", "obs3"), biglab = FALSE, hlines = NULL, + leg = TRUE, siglev = FALSE, sizetit = 1, show_conf = TRUE, + fileout = "output_plotvsltime.eps", width = 8, height = 5, + size_units = "in", res = 100, ...) } \arguments{ - \item{var}{ -Matrix containing any Prediction Score with dimensions:\cr - (nexp/nmod, 3/4 ,nltime)\cr - or (nexp/nmod, nobs, 3/4 ,nltime) - } - \item{toptitle}{ -Main title, optional. - } - \item{ytitle}{ -Title of Y-axis, optional. - } - \item{monini}{ -Starting month between 1 and 12. Default = 1. - } - \item{freq}{ -1 = yearly, 12 = monthly, 4 = seasonal, ... Default = 12. - } - \item{nticks}{ -Number of ticks and labels on the x-axis, optional. - } - \item{limits}{ -c(lower limit, upper limit): limits of the Y-axis, optional. - } - \item{listexp}{ -List of experiment names, optional. - } - \item{listobs}{ -List of observation names, optional. - } - \item{biglab}{ -TRUE/FALSE for presentation/paper plot. Default = FALSE. - } - \item{hlines}{ -c(a,b, ..) Add horizontal black lines at Y-positions a,b, ...\cr -Default = NULL. - } - \item{leg}{ -TRUE/FALSE if legend should be added or not to the plot. Default = TRUE. - } - \item{siglev}{ -TRUE/FALSE if significance level should replace confidence interval.\cr -Default = FALSE. - } - \item{sizetit}{ -Multiplicative factor to change title size, optional. - } - \item{show_conf}{ -TRUE/FALSE to show/not confidence intervals for input variables. - } - \item{fileout}{ -Name of output file. Extensions allowed: eps/ps, jpeg, png, pdf, bmp -and tiff.\cr -Default = 'output_plotvsltime.eps' - } - \item{width}{ -File width, in the units specified in the parameter size_units (inches by default). Takes 8 by default. - } - \item{height}{ -File height, in the units specified in the parameter size_units (inches by default). Takes 5 by default. - } - \item{size_units}{ -Units of the size of the device (file or window) to plot in. Inches ('in') by default. See ?Devices and the creator function of the corresponding device. - } - \item{res}{ -Resolution of the device (file or window) to plot in. See ?Devices and the creator function of the corresponding device. - } - \item{...}{ - Arguments to be passed to the method. Only accepts the following - graphical parameters: - - adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt csi cxy err family fg fig font font.axis font.lab font.main font.sub lheight ljoin lmitre mar mex mfcol mfrow mfg mkh oma omd omi page pch plt smo srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog - - For more information about the parameters see `par` - } +\item{var}{Matrix containing any Prediction Score with dimensions:\cr +(nexp/nmod, 3/4 ,nltime)\cr +or (nexp/nmod, nobs, 3/4 ,nltime).} + +\item{toptitle}{Main title, optional.} + +\item{ytitle}{Title of Y-axis, optional.} + +\item{monini}{Starting month between 1 and 12. Default = 1.} + +\item{freq}{1 = yearly, 12 = monthly, 4 = seasonal, ... Default = 12.} + +\item{nticks}{Number of ticks and labels on the x-axis, optional.} + +\item{limits}{c(lower limit, upper limit): limits of the Y-axis, optional.} + +\item{listexp}{List of experiment names, optional.} + +\item{listobs}{List of observation names, optional.} + +\item{biglab}{TRUE/FALSE for presentation/paper plot. Default = FALSE.} + +\item{hlines}{c(a,b, ..) Add horizontal black lines at Y-positions a,b, ...\cr +Default = NULL.} + +\item{leg}{TRUE/FALSE if legend should be added or not to the plot. +Default = TRUE.} + +\item{siglev}{TRUE/FALSE if significance level should replace confidence +interval.\cr +Default = FALSE.} + +\item{sizetit}{Multiplicative factor to change title size, optional.} + +\item{show_conf}{TRUE/FALSE to show/not confidence intervals for input +variables.} + +\item{fileout}{Name of output file. Extensions allowed: eps/ps, jpeg, png, +pdf, bmp and tiff.\cr +Default = 'output_plotvsltime.eps'} + +\item{width}{File width, in the units specified in the parameter size_units +(inches by default). Takes 8 by default.} + +\item{height}{File height, in the units specified in the parameter +size_units (inches by default). Takes 5 by default.} + +\item{size_units}{Units of the size of the device (file or window) to plot +in. Inches ('in') by default. See ?Devices and the creator function of the +corresponding device.} + +\item{res}{Resolution of the device (file or window) to plot in. See +?Devices and the creator function of the corresponding device.} + +\item{...}{Arguments to be passed to the method. Only accepts the following +graphical parameters:\cr +adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt +csi cxy err family fg fig font font.axis font.lab font.main font.sub +lheight ljoin lmitre mar mex mfcol mfrow mfg mkh oma omd omi page pch plt +smo srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog \cr +For more information about the parameters see `par`.} +} +\description{ +Plots The Correlation (\code{Corr()}) or the Root Mean Square Error +(\code{RMS()}) between the forecasted values and their observational +counterpart or the slopes of their trends (\code{Trend()}) or the +InterQuartile Range, Maximum-Mininum, Standard Deviation or Median Absolute +Deviation of the Ensemble Members (\code{Spread()}), or the ratio between +the Ensemble Spread and the RMSE of the Ensemble Mean (\code{RatioSDRMS()}) +along the forecast time for all the input experiments on the same figure +with their confidence intervals. } \details{ Examples of input:\cr - Model and observed output from \code{Load()} then \code{Clim()} then \code{Ano()} then \code{Smoothing()}:\cr - (nmod, nmemb, nsdate, nltime) and (nobs, nmemb, nsdate, nltime)\cr - then averaged over the members\cr - \code{Mean1Dim(var_exp/var_obs, posdim = 2)}:\cr - (nmod, nsdate, nltime) and (nobs, nsdate, nltime)\cr - then passed through\cr - \code{Corr(exp, obs, posloop = 1, poscor = 2)} or\cr - \code{RMS(exp, obs, posloop = 1, posRMS = 2)}:\cr - (nmod, nobs, 3, nltime)\cr - would plot the correlations or RMS between each exp & each obs as a function of the forecast time. +Model and observed output from \code{Load()} then \code{Clim()} then +\code{Ano()} then \code{Smoothing()}:\cr +(nmod, nmemb, nsdate, nltime) and (nobs, nmemb, nsdate, nltime)\cr +then averaged over the members\cr +\code{Mean1Dim(var_exp/var_obs, posdim = 2)}:\cr +(nmod, nsdate, nltime) and (nobs, nsdate, nltime)\cr +then passed through\cr + \code{Corr(exp, obs, posloop = 1, poscor = 2)} or\cr + \code{RMS(exp, obs, posloop = 1, posRMS = 2)}:\cr + (nmod, nobs, 3, nltime)\cr +would plot the correlations or RMS between each exp & each obs as a function +of the forecast time. } \examples{ # Load sample data as in Load() example: @@ -117,20 +113,22 @@ dim_to_mean <- 2 # Mean along members required_complete_row <- 3 # Discard startdates for which there are NA leadtimes leadtimes_per_startdate <- 60 corr <- Corr(Mean1Dim(smooth_ano_exp, dim_to_mean), - Mean1Dim(smooth_ano_obs, dim_to_mean), - compROW = required_complete_row, - limits = c(ceiling((runmean_months + 1) / 2), - leadtimes_per_startdate - floor(runmean_months / 2))) + Mean1Dim(smooth_ano_obs, dim_to_mean), + compROW = required_complete_row, + limits = c(ceiling((runmean_months + 1) / 2), + leadtimes_per_startdate - floor(runmean_months / 2))) PlotVsLTime(corr, toptitle = "correlations", ytitle = "correlation", - monini = 11, limits = c(-1, 2), listexp = c('CMIP5 IC3'), - listobs = c('ERSST'), biglab = FALSE, hlines = c(-1, 0, 1), - fileout = 'tos_cor.eps') + monini = 11, limits = c(-1, 2), listexp = c('CMIP5 IC3'), + listobs = c('ERSST'), biglab = FALSE, hlines = c(-1, 0, 1), + fileout = 'tos_cor.eps') + } \author{ History:\cr -0.1 - 2011-03 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -0.2 - 2013-03 (I. Andreu-Burillo, \email{isabel.andreu-burillo at ic3.cat}) - Introduced parameter sizetit\cr -0.3 - 2013-10 (I. Andreu-Burillo, \email{isabel.andreu-burillo at ic3.cat}) - Introduced parameter show_conf\cr -1.0 - 2013-11 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +0.2 - 2013-03 (I. Andreu-Burillo, \email{isabel.andreu-burillo@ic3.cat}) - Introduced parameter sizetit\cr +0.3 - 2013-10 (I. Andreu-Burillo, \email{isabel.andreu-burillo@ic3.cat}) - Introduced parameter show_conf\cr +1.0 - 2013-11 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{dynamic} + diff --git a/man/ProbBins.Rd b/man/ProbBins.Rd index 8bb763301aa539d45def771aa53ed272f5c8fc3e..6df49cc2e5abe05617b29c2a9c59845609a2441c 100644 --- a/man/ProbBins.Rd +++ b/man/ProbBins.Rd @@ -1,80 +1,89 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ProbBins.R \name{ProbBins} \alias{ProbBins} -\title{ -Computes Probabilistic Information of a Forecast Relative to a Threshold or a Quantile. -} -\description{ -Compute probabilistic bins of a set of forecast years ('fcyr') relative to the forecast climatology over the whole period of anomalies, optionally excluding the selected forecast years ('fcyr') or the forecast year for which the probabilistic bins are being computed (see 'compPeriod'). -} +\title{Computes Probabilistic Information of a Forecast Relative to a Threshold or a Quantile} \usage{ -ProbBins(ano, fcyr = 'all', thr, quantile = TRUE, posdates = 3, posdim = 2, - compPeriod = "Full period") +ProbBins(ano, fcyr = "all", thr, quantile = TRUE, posdates = 3, + posdim = 2, compPeriod = "Full period") } \arguments{ - \item{ano}{ -Array of anomalies from Ano().\cr -Must be of dimension (nexp/nobs, nmemb, nsdates, nleadtime, nlat, nlon) - } - \item{fcyr}{ -Indices of the forecast years of the anomalies which to compute the probabilistic bins for, or 'all' to compute the bins for all the years.\cr -Ex: c(1:5), c(1, 4), 4 or 'all'. - } - \item{thr}{ -Values used as thresholds to bin the anomalies. - } - \item{quantile}{ -If quantile is TRUE (default), the threshold ('thr') are quantiles.\cr -If quantile is FALSE the thresholds ('thr') introduced are the absolute thresholds of the bins. - } - \item{posdates}{ -Position of the dimension in \code{ano} that corresponds to the start dates (default = 3). - } - \item{posdim}{ -Position of the dimension in \code{ano} which will be combined with 'posdates' to compute the quantiles (default = 2, ensemble members). - } - \item{compPeriod}{ -Three options: "Full period"/"Without fcyr"/"Cross-validation" (The probabilities are computed with the terciles based on ano/ano with all 'fcyr's removed/cross-validation). The default is "Full period". - } +\item{ano}{Array of anomalies from Ano().\cr +Must be of dimension (nexp/nobs, nmemb, nsdates, nleadtime, nlat, nlon)} + +\item{fcyr}{Indices of the forecast years of the anomalies which to compute +the probabilistic bins for, or 'all' to compute the bins for all the +years.\cr +E.g., c(1:5), c(1, 4), 4 or 'all'.} + +\item{thr}{Values used as thresholds to bin the anomalies.} + +\item{quantile}{If quantile is TRUE (default), the threshold ('thr') +are quantiles.\cr +If quantile is FALSE the thresholds ('thr') introduced are the absolute +thresholds of the bins.} + +\item{posdates}{Position of the dimension in \code{ano} that corresponds to +the start dates (default = 3).} + +\item{posdim}{Position of the dimension in \code{ano} which will be combined +with 'posdates' to compute the quantiles (default = 2, ensemble members).} + +\item{compPeriod}{Three options: +"Full period"/"Without fcyr"/"Cross-validation" (The probabilities are +computed with the terciles based on ano/ano with all 'fcyr's +removed/cross-validation). The default is "Full period".} } \value{ Array with probabilistic information and dimensions:\cr -c(length('thr') + 1, length(fcyr), nmemb/nparam, nmod/nexp/nobs, nltime, nlat, nlon)\cr -The values along the first dimension take values 0 or 1 depending on which of the 'thr'+1 cathegories the forecast/observation at the corresponding grid point, time step, member and starting date belongs to. + c(length('thr') + 1, length(fcyr), nmemb/nparam, nmod/nexp/nobs, + nltime, nlat, nlon)\cr + The values along the first dimension take values 0 or 1 depending on which + of the 'thr'+1 cathegories the forecast/observation at the corresponding + grid point, time step, member and starting date belongs to. +} +\description{ +Compute probabilistic bins of a set of forecast years ('fcyr') relative to +the forecast climatology over the whole period of anomalies, optionally excluding +the selected forecast years ('fcyr') or the forecast year for which the +probabilistic bins are being computed (see 'compPeriod'). } \examples{ # See examples on Load() to understand the first lines in this example - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') expA <- list(name = 'experiment', path = file.path(data_path, - 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', - '$VAR_NAME$_$START_DATE$.nc')) + 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', + '$VAR_NAME$_$START_DATE$.nc')) obsX <- list(name = 'observation', path = file.path(data_path, - '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', - '$VAR_NAME$_$YEAR$$MONTH$.nc')) + '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', + '$VAR_NAME$_$YEAR$$MONTH$.nc')) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(expA), list(obsX), startDates, - output = 'lonlat', latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } - \dontshow{ + output = 'lonlat', latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } + \dontshow{ startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - output = 'lonlat', - latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } + c('observation'), startDates, + output = 'lonlat', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } clim <- Clim(sampleMap$mod, sampleMap$obs) ano_exp <- Ano(sampleMap$mod, clim$clim_exp) PB <- ProbBins(ano_exp, fcyr = 3, thr = c(1/3, 2/3), quantile = TRUE, posdates = 3, - posdim = 2) + posdim = 2) + } \author{ History:\cr 1.0 - 2013 (F.Lienert) - Original code\cr -2.0 - 2014-03 (N. Gonzalez and V. Torralba, \email{veronica.torralba at bsc.es}) - Debugging -2.1 - 2017-02 (V. Torralba and N. Manubens, \email{veronica.torralba at bsc.es}) - Fix bug with cross-validation +2.0 - 2014-03 (N. Gonzalez and V. Torralba, \email{veronica.torralba@bsc.es}) - Debugging +2.1 - 2017-02 (V. Torralba and N. Manubens, \email{veronica.torralba@bsc.es}) - Fix bug with cross-validation } \keyword{datagen} + diff --git a/man/ProjectField.Rd b/man/ProjectField.Rd index 91d33039da5d432fc3df07f93b95d0900f35478c..7b2e9e93741e3119af030346dc6b0af59f3fec83 100644 --- a/man/ProjectField.Rd +++ b/man/ProjectField.Rd @@ -1,60 +1,59 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ProjectField.R \name{ProjectField} \alias{ProjectField} -\title{ -Project Anomalies onto Modes of Variability -} -\description{ -Project anomalies onto modes of variability to get the temporal evolution of the EOF mode\cr -selected. Returns principal components (PCs) by area-weighted projection -onto EOF pattern (from \code{EOF()}). Able to handle NAs. -} +\title{Project Anomalies onto Modes of Variability} \usage{ ProjectField(ano, eof, mode = 1) } \arguments{ - \item{ano}{ -Array of forecast or observational reference anomalies from \code{Ano()} or -\code{Ano_CrossValid} with dimensions (number of forecast systems, ensemble -members, start dates, forecast horizons, latitudes, longitudes). - } - \item{eof}{ -R object with EOFs from \code{EOF}. - } - \item{mode}{ -Variability mode number in the provided EOF object which to project onto. - } +\item{ano}{Array of forecast or observational reference anomalies from +\code{Ano()} or \code{Ano_CrossValid} with dimensions (number of forecast +systems, ensemble members, start dates, forecast horizons, latitudes, +longitudes).} + +\item{eof}{R object with EOFs from \code{EOF}.} + +\item{mode}{Variability mode number in the provided EOF object which to +project onto.} } \value{ -Array of principal components in verification format (number of forecast -systems, ensemble members, start dates, forecast horizons). +Array of principal components in verification format (number of + forecast systems, ensemble members, start dates, forecast horizons). +} +\description{ +Project anomalies onto modes of variability to get the temporal evolution of +the EOF mode selected. Returns principal components (PCs) by +area-weighted projection onto EOF pattern (from \code{EOF()}). +Able to handle NAs. } \examples{ # See examples on Load() to understand the first lines in this example - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') expA <- list(name = 'experiment', path = file.path(data_path, - 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', - '$VAR_NAME$_$START_DATE$.nc')) + 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', + '$VAR_NAME$_$START_DATE$.nc')) obsX <- list(name = 'observation', path = file.path(data_path, - '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', - '$VAR_NAME$_$YEAR$$MONTH$.nc')) + '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', + '$VAR_NAME$_$YEAR$$MONTH$.nc')) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(expA), list(obsX), startDates, - leadtimemin = 1, leadtimemax = 4, output = 'lonlat', - latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) - } - \dontshow{ + leadtimemin = 1, leadtimemax = 4, output = 'lonlat', + latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) + } + \dontshow{ startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - leadtimemin = 1, - leadtimemax = 4, - output = 'lonlat', - latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } + c('observation'), startDates, + leadtimemin = 1, + leadtimemax = 4, + output = 'lonlat', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } # Now ready to compute the EOFs and project. ano <- Ano_CrossValid(sampleData$mod, sampleData$obs) @@ -70,40 +69,44 @@ mode1_obs <- ProjectField(ano$ano_obs, eof, 1) # for the last year of forecast plot(mode1_obs[1, 1, dim(sampleData$mod)[3], ], type = "l", ylim = c(-1, 1), lwd = 2) for (i in 1:dim(sampleData$mod)[2]) { - par(new = TRUE) - plot(mode1_exp[1, i, dim(sampleData$mod)[3], ], type = "l", col = rainbow(10)[i], - ylim = c(-15000, 15000)) + par(new = TRUE) + plot(mode1_exp[1, i, dim(sampleData$mod)[3], ], type = "l", col = rainbow(10)[i], + ylim = c(-15000, 15000)) } + } \author{ History:\cr -0.1 - 2012-03 (F. Lienert, \email{flienert at ic3.cat} - Original code -0.2 - 2014-03 (Lauriane Batte, \email{lauriane.batte at ic3.cat} - Bug-fixes:\cr - 1- Extra weighting of the anomalies before projection.\cr - 2- Reversion of the anomalies along latitudes.\cr - 3- Extra-normalisation not necessary.\cr -0.3 - 2014-03 (Virginie Guemas, \email{virginie.guemas at bsc.es} - Bug-fixes:\cr - 1- Another extra-normalisation.\cr - 2- 15 lines to compute the em reduced to 1. -0.4 - 2014-03 (Lauriane Batte, \email{lauriane.batte at ic3.cat} - Normalization\cr +0.1 - 2012-03 (F. Lienert, \email{flienert@ic3.cat} - Original code\cr +0.2 - 2014-03 (Lauriane Batte, \email{lauriane.batte@ic3.cat} - Bug-fixes:\cr + 1- Extra weighting of the anomalies before projection.\cr + 2- Reversion of the anomalies along latitudes.\cr + 3- Extra-normalisation not necessary.\cr +0.3 - 2014-03 (Virginie Guemas, \email{virginie.guemas@bsc.es} - Bug-fixes:\cr + 1- Another extra-normalisation.\cr + 2- 15 lines to compute the em reduced to 1. +0.4 - 2014-03 (Lauriane Batte, \email{lauriane.batte@ic3.cat} - Normalization\cr by std before returning PCs to be coherent with EOF().\cr -0.5 - 2014-04 (Virginie Guemas, \email{virginie.guemas at bsc.es} - Fixes:\cr - 1- Removal of lon, lat, ncpu and neofs argument unused\cr - 2- Security checks ano and eof consistency\cr - 3- Removal of the mask which is already contained in the EOFs\cr - 4- Removal of the PC normalization since we have chosen in\cr +0.5 - 2014-04 (Virginie Guemas, \email{virginie.guemas@bsc.es} - Fixes:\cr + 1- Removal of lon, lat, ncpu and neofs argument unused\cr + 2- Security checks ano and eof consistency\cr + 3- Removal of the mask which is already contained in the EOFs\cr + 4- Removal of the PC normalization since we have chosen in\cr \code{EOF()} to normalize the EOFs and multiply the PCs by the normalization\cr factor and the eigenvalue so that the restitution of the original field is \cr done simply by PC * EOFs\cr - 5 - The new convention in \code{EOF()} is to divide by the weights\cr + 5 - The new convention in \code{EOF()} is to divide by the weights\cr so that the reconstruction of the original field rather than the weighted\cr field is obtained by PC * EOFs. The EOFs need therefore to be multiplied \cr back by the weights before projection so that EOF * t(EOF) = 1\cr - 6 - Since W *X = PC * EOF if EOF is multiplied back by the weights,\cr + 6 - Since W *X = PC * EOF if EOF is multiplied back by the weights,\cr PC = W * X * t(EOF) and X the input field to be projected (X) needs to be\cr multiplied by W. Getting input dimensions. -1.0 - 2016-03 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Formatting to R CRAN - (J.-P. Baudouin, \email{jean.baudouin at bsc.es}) - Example code and testing +1.0 - 2016-03 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Formatting to R CRAN\cr + (J.-P. Baudouin, \email{jean.baudouin@bsc.es}) - Example code and testing +} +\seealso{ +EOF, NAO, PlotBoxWhisker } -\seealso{EOF, NAO, PlotBoxWhisker} \keyword{datagen} + diff --git a/man/RMS.Rd b/man/RMS.Rd index 874fb969b8bda396f2b363242b5e4a9d22fb24e4..cf26c75cb7c8dbfb48b5182c73b521bc0f61d916 100644 --- a/man/RMS.Rd +++ b/man/RMS.Rd @@ -1,72 +1,79 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/RMS.R \name{RMS} -\alias{RMS} \alias{.RMS} -\title{ -Computes Root Mean Square Error -} -\description{ -Computes the root mean square error for an array of forecasts, var_exp and an array of observations, var_obs, which should have the same dimensions except along the posloop dimension where the lengths can be different, with the number of experiments/models for var_exp (nexp) and the number of obserational datasets for var_obs (nobs).\cr -The RMSE is computed along the posRMS dimension which should correspond to the startdate dimension.\cr -If compROW is given, the RMSE is computed only if rows along the compROW dimension are complete between limits[1] and limits[2], i.e. there are no NAs between limits[1] and limits[2]. This option can be activated if the user wishes to account only for the forecasts for which observations are available at all leadtimes.\cr -Default: limits[1] = 1 and limits[2] = length(compROW dimension).\cr -The confidence interval relies on a chi2 distribution.\cr -\cr -.RMS provides the same functionality but taking a matrix of ensemble members as input (exp). -} +\alias{RMS} +\title{Computes Root Mean Square Error} \usage{ -RMS(var_exp, var_obs, posloop = 1, posRMS = 2, compROW = NULL, - limits = NULL, siglev = 0.95, conf = TRUE) +RMS(var_exp, var_obs, posloop = 1, posRMS = 2, compROW = NULL, + limits = NULL, siglev = 0.95, conf = TRUE) -.RMS(exp, obs, siglev = 0.95, conf = TRUE) +.RMS(exp, obs, siglev = 0.95, conf = TRUE) } \arguments{ - \item{var_exp}{ -Matrix of experimental data. - } - \item{var_obs}{ -Matrix of observational data, same dimensions as var_exp except along posloop dimension, where the length can be nobs instead of nexp. - } - \item{posloop}{ -Dimension nobs and nexp. - } - \item{posRMS}{ -Dimension along which RMSE are to be computed (the dimension of the start dates). - } - \item{compROW}{ -Data taken into account only if (compROW)th row is complete.\cr -Default = NULL. - } - \item{limits}{ -Complete between limits[1] & limits[2]. Default = NULL. - } - \item{siglev}{ -Confidence level of the computed confidence interval. 0.95 by default. - } - \item{conf}{ -Whether to compute confidence interval or not. TRUE by default. - } - \item{exp}{ -N by M matrix of N forecasts from M ensemble members. - } - \item{obs}{ -Vector of the corresponding observations of length N. - } +\item{var_exp}{Matrix of experimental data.} + +\item{var_obs}{Matrix of observational data, same dimensions as var_exp +except along posloop dimension, where the length can be nobs instead of +nexp.} + +\item{posloop}{Dimension nobs and nexp.} + +\item{posRMS}{Dimension along which RMSE are to be computed (the dimension +of the start dates).} + +\item{compROW}{Data taken into account only if (compROW)th row is complete.\cr +Default = NULL.} + +\item{limits}{Complete between limits[1] & limits[2]. Default = NULL.} + +\item{siglev}{Confidence level of the computed confidence interval. 0.95 +by default.} + +\item{conf}{Whether to compute confidence interval or not. TRUE by default.} + +\item{exp}{N by M matrix of N forecasts from M ensemble members.} + +\item{obs}{Vector of the corresponding observations of length N.} } \value{ RMS: Array with dimensions:\cr - c(length(posloop) in var_exp, length(posloop) in var_obs, 1 or 3, all other dimensions of var_exp & var_obs except posRMS).\cr -The 3rd dimension corresponds to the lower limit of the 95\% confidence interval (only present if \code{conf = TRUE}), the RMSE, and the upper limit of the 95\% confidence interval (only present if \code{conf = TRUE}). \cr -\cr +c(length(posloop) in var_exp, length(posloop) in var_obs, 1 or 3, all + other dimensions of var_exp & var_obs except posRMS).\cr +The 3rd dimension corresponds to the lower limit of the 95\% confidence + interval (only present if \code{conf = TRUE}), the RMSE, and the upper + limit of the 95\% confidence interval (only present if + \code{conf = TRUE}).\cr\cr .RMS: - \item{$rms}{ +\item{$rms}{ The root mean square error, - } - \item{$conf_low}{ -Corresponding to the lower limit of the \code{siglev}\% confidence interval (only present if \code{conf = TRUE}) for the rms. - } - \item{$conf_high}{ -Corresponding to the upper limit of the \code{siglev}\% confidence interval (only present if \code{conf = TRUE}) for the rms. - } +} +\item{$conf_low}{ + Corresponding to the lower limit of the \code{siglev}\% confidence interval + (only present if \code{conf = TRUE}) for the rms. +} +\item{$conf_high}{ + Corresponding to the upper limit of the \code{siglev}\% confidence interval + (only present if \code{conf = TRUE}) for the rms. +} +} +\description{ +Computes the root mean square error for an array of forecasts, var_exp and +an array of observations, var_obs, which should have the same dimensions +except along the posloop dimension where the lengths can be different, with +the number of experiments/models for var_exp (nexp) and the number of +obserational datasets for var_obs (nobs).\cr +The RMSE is computed along the posRMS dimension which should correspond to +the startdate dimension.\cr +If compROW is given, the RMSE is computed only if rows along the compROW +dimension are complete between limits[1] and limits[2], i.e. there are no +NAs between limits[1] and limits[2]. This option can be activated if the +user wishes to account only for the forecasts for which observations are +available at all leadtimes.\cr +Default: limits[1] = 1 and limits[2] = length(compROW dimension).\cr +The confidence interval relies on a chi2 distribution.\cr\cr +.RMS provides the same functionality but taking a matrix of ensemble +members as input (exp). } \examples{ # Load sample data as in Load() example: @@ -83,29 +90,31 @@ dim_to_mean <- 2 # Mean along members required_complete_row <- 3 leadtimes_per_startdate <- 60 rms <- RMS(Mean1Dim(smooth_ano_exp, dim_to_mean), - Mean1Dim(smooth_ano_obs, dim_to_mean), - compROW = required_complete_row, - limits = c(ceiling((runmean_months + 1) / 2), - leadtimes_per_startdate - floor(runmean_months / 2))) + Mean1Dim(smooth_ano_obs, dim_to_mean), + compROW = required_complete_row, + limits = c(ceiling((runmean_months + 1) / 2), + leadtimes_per_startdate - floor(runmean_months / 2))) PlotVsLTime(rms, toptitle = "Root Mean Square Error", ytitle = "K", - monini = 11, limits = NULL, listexp = c('CMIP5 IC3'), - listobs = c('ERSST'), biglab = FALSE, hlines = c(0), - fileout = 'tos_rms.eps') + monini = 11, limits = NULL, listexp = c('CMIP5 IC3'), + listobs = c('ERSST'), biglab = FALSE, hlines = c(0), + fileout = 'tos_rms.eps') # The following example uses veriApply combined with .RMS instead of RMS - \dontrun{ + \dontrun{ require(easyVerification) RMS2 <- s2dverification:::.RMS rms2 <- veriApply("RMS2", - smooth_ano_exp, - # see ?veriApply for how to use the 'parallel' option - Mean1Dim(smooth_ano_obs, dim_to_mean), - tdim = 3, ensdim = 2) - } + smooth_ano_exp, + # see ?veriApply for how to use the 'parallel' option + Mean1Dim(smooth_ano_obs, dim_to_mean), + tdim = 3, ensdim = 2) + } + } \author{ History:\cr -0.1 - 2011-05 (V. Guemas, \email{vguemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to R CRAN\cr -1.1 - 2017-02 (A. Hunter, \email{alasdair.hunter at bsc.es}) - Adapted to veriApply() +0.1 - 2011-05 (V. Guemas, \email{vguemas@ic3.cat}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens2@ic3.cat}) - Formatting to R CRAN\cr +1.1 - 2017-02 (A. Hunter, \email{alasdair.hunter@bsc.es}) - Adapted to veriApply() } \keyword{datagen} + diff --git a/man/RMSSS.Rd b/man/RMSSS.Rd index b7a994a7765784cfcb6c036209261a340606839b..234170b86f376b2e4bc993324b930e82e7d172d5 100644 --- a/man/RMSSS.Rd +++ b/man/RMSSS.Rd @@ -1,59 +1,64 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/RMSSS.R \name{RMSSS} -\alias{RMSSS} \alias{.RMSSS} -\title{ -Computes Root Mean Square Skill Score -} -\description{ -Computes the root mean square error skill score between an array of forecasts, var_exp and an array of observations, var_obs, which should have the same dimensions except along posloop where the lengths can be different, with the number of experiments/models for var_exp (nexp) and the number of obserational datasets for var_obs (nobs).\cr -RMSSS computes the Root Mean Square Skill Score of each jexp in 1:nexp against each jobs in 1:nobs which gives nexp x nobs RMSSS for each other grid point of the matrix (each latitude/longitude/level/leadtime).\cr -The RMSSS are computed along the posRMS dimension which should correspond to the startdate dimension.\cr -The p-value is optionally provided by a one-sided Fisher test.\cr -\cr -.RMSSS provides the same functionality but taking a matrix of ensemble members as input (exp). -} +\alias{RMSSS} +\title{Computes Root Mean Square Skill Score} \usage{ RMSSS(var_exp, var_obs, posloop = 1, posRMS = 2, pval = TRUE) .RMSSS(exp, obs, pval = TRUE) } \arguments{ - \item{var_exp}{ -Array of experimental data. - } - \item{var_obs}{ -Array of observational data, same dimensions as var_exp except along posloop dimension, where the length can be nobs instead of nexp. - } - \item{posloop}{ -Dimension nobs and nexp. - } - \item{posRMS}{ -Dimension along which the RMSE are to be computed (the dimension of the start dates). - } - \item{pval}{ -Whether to compute or not the p-value of the test Ho : RMSSS = 0. TRUE by default. - } - \item{exp}{ -N by M matrix of N forecasts from M ensemble members. - } - \item{obs}{ -Vector of the corresponding observations of length N. - } +\item{var_exp}{Array of experimental data.} + +\item{var_obs}{Array of observational data, same dimensions as var_exp +except along posloop dimension, where the length can be nobs instead of +nexp.} + +\item{posloop}{Dimension nobs and nexp.} + +\item{posRMS}{Dimension along which the RMSE are to be computed (the +dimension of the start dates).} + +\item{pval}{Whether to compute or not the p-value of the test Ho : +RMSSS = 0. TRUE by default.} + +\item{exp}{N by M matrix of N forecasts from M ensemble members.} + +\item{obs}{Vector of the corresponding observations of length N.} } \value{ RMSSS: Array with dimensions:\cr - c(length(posloop) in var_exp, length(posloop) in var_obs, 1 or 2, all other dimensions of var_exp & var_obs except posRMS).\cr -The 3rd dimension corresponds to the RMSSS and, if \code{pval = TRUE}, the p-value of the one-sided Fisher test with Ho: RMSSS = 0.\cr -\cr + c(length(posloop) in var_exp, length(posloop) in var_obs, 1 or 2, + all other dimensions of var_exp & var_obs except posRMS).\cr +The 3rd dimension corresponds to the RMSSS and, if \code{pval = TRUE}, + the p-value of the one-sided Fisher test with Ho: RMSSS = 0.\cr\cr .RMSSS: - \itemize{ - \item{$rmsss}{ -The RMSSS. - } - \item{$p_val}{ -Corresponds to the p values (only present if \code{pval = TRUE}) for the RMSSS. - } - } + \itemize{ + \item{$rmsss}{ + The RMSSS. + } + \item{$p_val}{ + Corresponds to the p values (only present if \code{pval = TRUE}) for + the RMSSS. + } + } +} +\description{ +Computes the root mean square error skill score between an array of +forecasts, var_exp and an array of observations, var_obs, which should +have the same dimensions except along posloop where the lengths can be +different, with the number of experiments/models for var_exp (nexp) and +the number of obserational datasets for var_obs (nobs).\cr +RMSSS computes the Root Mean Square Skill Score of each jexp in 1:nexp +against each jobs in 1:nobs which gives nexp x nobs RMSSS for each other +grid point of the matrix (each latitude/longitude/level/leadtime).\cr +The RMSSS are computed along the posRMS dimension which should correspond +to the startdate dimension.\cr +The p-value is optionally provided by a one-sided Fisher test.\cr\cr +.RMSSS provides the same functionality but taking a matrix of ensemble +members as input (exp). } \examples{ # Load sample data as in Load() example: @@ -66,23 +71,24 @@ rmsss_plot <- array(dim = c(dim(rmsss)[1:2], 4, dim(rmsss)[4])) rmsss_plot[, , 2, ] <- rmsss[, , 1, ] rmsss_plot[, , 4, ] <- rmsss[, , 2, ] PlotVsLTime(rmsss_plot, toptitle = "Root Mean Square Skill Score", ytitle = "", - monini = 11, limits = c(-1, 1.3), listexp = c('CMIP5 IC3'), - listobs = c('ERSST'), biglab = FALSE, hlines = c(-1, 0, 1), - fileout = 'tos_rmsss.eps') + monini = 11, limits = c(-1, 1.3), listexp = c('CMIP5 IC3'), + listobs = c('ERSST'), biglab = FALSE, hlines = c(-1, 0, 1), + fileout = 'tos_rmsss.eps') # The following example uses veriApply combined with .RMSSS instead of RMSSS - \dontrun{ + \dontrun{ require(easyVerification) RMSSS2 <- s2dverification:::.RMSSS rmsss2 <- veriApply("RMSSS2", ano_exp, - # see ?veriApply for how to use the 'parallel' option - Mean1Dim(ano_obs, 2), - tdim = 3, ensdim = 2) - } + # see ?veriApply for how to use the 'parallel' option + Mean1Dim(ano_obs, 2), + tdim = 3, ensdim = 2) + } } \author{ History:\cr -0.1 - 2012-04 (V. Guemas, \email{vguemas at bsc.es}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Formatting to R CRAN\cr -1.1 - 2017-02 (A. Hunter, \email{alasdair.hunter at bsc.es}) - Adapted to veriApply() +0.1 - 2012-04 (V. Guemas, \email{vguemas@bsc.es}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Formatting to R CRAN\cr +1.1 - 2017-02 (A. Hunter, \email{alasdair.hunter@bsc.es}) - Adapted to veriApply() } \keyword{datagen} + diff --git a/man/RatioRMS.Rd b/man/RatioRMS.Rd index aa179b769e2b9603fcf1dd056c113feed22c84f6..44d13dbb5b33126c309e549849313102e315ddce 100644 --- a/man/RatioRMS.Rd +++ b/man/RatioRMS.Rd @@ -1,91 +1,87 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/RatioRMS.R \name{RatioRMS} -\alias{RatioRMS} \alias{.RatioRMS} -\title{ -Computes the Ratio Between The RMSE of Two Experiments -} -\description{ -Calculates the ratio of the RMSE for two forecasts of the same observations.\cr -The ratio RMSE(ens, obs) / RMSE(ens.ref, obs) is output.\cr -The p-value is provided by a two-sided Fischer test.\cr -\cr -.RatioRMS provides the same functionality but taking two matrices of ensemble members (ens and ens.ref) as input. -} +\alias{RatioRMS} +\title{Computes the Ratio Between The RMSE of Two Experiments} \usage{ RatioRMS(var_exp1, var_exp2, var_obs, posRMS = 1, pval = TRUE) .RatioRMS(exp, exp_ref, obs, pval = TRUE) } \arguments{ - \item{var_exp1}{ -Array of experimental data 1. - } - \item{var_exp2}{ -Array of experimental data 2. - } - \item{var_obs}{ -Array of observations. - } - \item{posRMS}{ -Dimension along which the RMSE are to be computed = the position of the start dates. - } - \item{pval}{ -Whether to compute the p-value of Ho : RMSE1/RMSE2 = 1 or not. TRUE by default. - } - \item{exp}{ -Matrix of experimental data 1. - } - \item{exp_ref}{ -Matrix of experimental data 2. - } - \item{obs}{ -Vector of observations. - } +\item{var_exp1}{Array of experimental data 1.} + +\item{var_exp2}{Array of experimental data 2.} + +\item{var_obs}{Array of observations.} + +\item{posRMS}{Dimension along which the RMSE are to be computed = the +position of the start dates.} + +\item{pval}{Whether to compute the p-value of Ho : RMSE1/RMSE2 = 1 or not. +TRUE by default.} + +\item{exp}{Matrix of experimental data 1.} + +\item{exp_ref}{Matrix of experimental data 2.} + +\item{obs}{Vector of observations.} } \value{ RatioRMS:\cr -Matrix with the same dimensions as var_exp1/var_exp2/var_obs except along posRMS where the dimension has length 2 if 'pval = TRUE', or 1 otherwise. The dimension of length 2 corresponds to the ratio between the RMSE (RMSE1/RMSE2) and the p-value of the two-sided Fisher test with Ho: RMSE1/RMSE2 = 1.\cr -\cr +Matrix with the same dimensions as var_exp1/var_exp2/var_obs except along + posRMS where the dimension has length 2 if 'pval = TRUE', or 1 otherwise. + The dimension of length 2 corresponds to the ratio between the RMSE + (RMSE1/RMSE2) and the p-value of the two-sided Fisher test with Ho: + RMSE1/RMSE2 = 1.\cr\cr .RatioRMS:\cr - \itemize{ - \item{ratiorms}{The ratio of the RMSE of the two experimental datasets} - \item{p_val}{The p-value} - } + \itemize{ + \item{ratiorms}{The ratio of the RMSE of the two experimental datasets} + \item{p_val}{The p-value} + } +} +\description{ +Calculates the ratio of the RMSE for two forecasts of the same observations.\cr +The ratio RMSE(ens, obs) / RMSE(ens.ref, obs) is output.\cr +The p-value is provided by a two-sided Fischer test.\cr\cr +.RatioRMS provides the same functionality but taking two matrices of +ensemble members (ens and ens.ref) as input. } \examples{ # See examples on Load() to understand the first lines in this example - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') expA <- list(name = 'experiment', path = file.path(data_path, - 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', - '$VAR_NAME$_$START_DATE$.nc')) + 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', + '$VAR_NAME$_$START_DATE$.nc')) obsX <- list(name = 'observation', path = file.path(data_path, - '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', - '$VAR_NAME$_$YEAR$$MONTH$.nc')) + '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', + '$VAR_NAME$_$YEAR$$MONTH$.nc')) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(expA), list(obsX), startDates, - output = 'lonlat', latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } - \dontshow{ + output = 'lonlat', latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } + \dontshow{ startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - output = 'lonlat', - latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } + c('observation'), startDates, + output = 'lonlat', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } # Compute DJF seasonal means and anomalies. leadtimes_dimension <- 4 initial_month <- 11 mean_start_month <- 12 mean_stop_month <- 2 sampleData$mod <- Season(sampleData$mod, leadtimes_dimension, initial_month, - mean_start_month, mean_stop_month) + mean_start_month, mean_stop_month) sampleData$obs <- Season(sampleData$obs, leadtimes_dimension, initial_month, - mean_start_month, mean_stop_month) + mean_start_month, mean_stop_month) clim <- Clim(sampleData$mod, sampleData$obs) ano_exp <- Ano(sampleData$mod, clim$clim_exp) ano_obs <- Ano(sampleData$obs, clim$clim_obs) @@ -99,29 +95,30 @@ ano_exp_2 <- Subset(ano_exp_2, c('dataset', 'ftime'), list(1, 1), drop = 'select ano_obs <- Subset(ano_obs, c('dataset', 'ftime'), list(1, 1), drop = 'selected') # Compute ensemble mean and provide as inputs to RatioRMS. rrms <- RatioRMS(Mean1Dim(ano_exp_1, 1), - Mean1Dim(ano_exp_2, 1), - Mean1Dim(ano_obs, 1)) + Mean1Dim(ano_exp_2, 1), + Mean1Dim(ano_obs, 1)) # Plot the RatioRMS for the first forecast time step. PlotEquiMap(rrms[1, , ], sampleData$lon, sampleData$lat, - toptitle = 'Ratio RMSE') + toptitle = 'Ratio RMSE') # The following example uses veriApply combined with .RatioRMS instead of RatioRMS - \dontrun{ + \dontrun{ require(easyVerification) # The name of the function has to end in 'ss' in order for veriApply() to # detect it as a skill score. RatioRMSss <- s2dverification:::.RatioRMS rrms2 <- veriApply("RatioRMSss", ano_exp_1, - # see ?veriApply for how to use the 'parallel' option - Mean1Dim(ano_obs, 1), - ano_exp_2, - tdim = 2, ensdim = 1) - } + # see ?veriApply for how to use the 'parallel' option + Mean1Dim(ano_obs, 1), + ano_exp_2, + tdim = 2, ensdim = 1) + } } \author{ History:\cr -0.1 - 2011-11 (V. Guemas, \email{vguemas at bsc.es}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Formatting to R CRAN\cr -1.1 - 2017-02 (A. Hunter, \email{alasdair.hunter at bsc.es}) - Adapted to veriApply() +0.1 - 2011-11 (V. Guemas, \email{vguemas@bsc.es}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Formatting to R CRAN\cr +1.1 - 2017-02 (A. Hunter, \email{alasdair.hunter@bsc.es}) - Adapted to veriApply() } \keyword{datagen} + diff --git a/man/RatioSDRMS.Rd b/man/RatioSDRMS.Rd index 1e6a9f9da7adeb4908582cf71d144d653c797cc4..bb5848a5c71ca3f04d93a0ae66d7d4114072d47c 100644 --- a/man/RatioSDRMS.Rd +++ b/man/RatioSDRMS.Rd @@ -1,59 +1,57 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/RatioSDRMS.R \name{RatioSDRMS} -\alias{RatioSDRMS} \alias{.RatioSDRMS} -\title{ -Computes the ratio between the ensemble spread and RMSE -} -\description{ -Arrays var_exp & var_obs should have dimensions between\cr - c(nmod/nexp, nmemb/nparam, nsdates, nltime)\cr -and\cr - c(nmod/nexp, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon)\cr -The ratio between the standard deviation of the members around the ensemble mean in var_exp and the RMSE between var_exp and var_obs is output for each experiment and each observational dataset.\cr -The p-value is provided by a one-sided Fischer test.\cr -\cr -.RatioSDRMS provides the same functionality but taking a matrix of ensemble members as input (exp). -} +\alias{RatioSDRMS} +\title{Computes the ratio between the ensemble spread and RMSE} \usage{ RatioSDRMS(var_exp, var_obs, pval = TRUE) .RatioSDRMS(exp, obs, pval = TRUE) } \arguments{ - \item{var_exp}{ -Model data:\cr - c(nmod/nexp, nmemb/nparam, nsdates, nltime) up to\cr - c(nmod/nexp, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon) - } - \item{var_obs}{ -Observational data:\cr - c(nobs, nmemb, nsdates, nltime) up to\cr - c(nobs, nmemb, nsdates, nltime, nlevel, nlat, nlon) - } - \item{pval}{ -Whether to compute the p-value of Ho : SD/RMSE = 1 or not. - } - \item{exp}{ -N by M matrix of N forecasts from M ensemble members. - } - \item{obs}{ -Vector of the corresponding observations of length N. - } +\item{var_exp}{Model data:\cr +c(nmod/nexp, nmemb/nparam, nsdates, nltime) up to\cr +c(nmod/nexp, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon)} + +\item{var_obs}{Observational data:\cr +c(nobs, nmemb, nsdates, nltime) up to\cr +c(nobs, nmemb, nsdates, nltime, nlevel, nlat, nlon)} + +\item{pval}{Whether to compute the p-value of Ho : SD/RMSE = 1 or not.} + +\item{exp}{N by M matrix of N forecasts from M ensemble members.} + +\item{obs}{Vector of the corresponding observations of length N.} } \value{ -RatioSDRMS: Array with dimensions c(nexp/nmod, nobs, 1 or 2, nltime) up to - c(nexp/nmod, nobs, 1 or 2, nltime, nlevel, nlat, nlon). \cr -The 3rd dimension corresponds to the ratio (SD/RMSE) and the p.value (only present if \code{pval = TRUE}) of the one-sided Fisher test with Ho: SD/RMSE = 1.\cr -\cr +RatioSDRMS: Array with dimensions c(nexp/nmod, nobs, 1 or 2, nltime) + up to c(nexp/nmod, nobs, 1 or 2, nltime, nlevel, nlat, nlon).\cr +The 3rd dimension corresponds to the ratio (SD/RMSE) and the p.value +(only present if \code{pval = TRUE}) of the one-sided Fisher test with +Ho: SD/RMSE = 1.\cr\cr .RatioSDRMS: - \itemize{ - \item{$ratio}{ -The ratio of the ensemble spread and RMSE, - } - \item{$p_val}{ -Corresponds to the p values of the ratio (only present if \code{pval = TRUE}). - } - } + \itemize{ + \item{$ratio}{ + The ratio of the ensemble spread and RMSE, + } + \item{$p_val}{ + Corresponds to the p values of the ratio (only present if + \code{pval = TRUE}). + } + } +} +\description{ +Arrays var_exp & var_obs should have dimensions between\cr +c(nmod/nexp, nmemb/nparam, nsdates, nltime)\cr +and\cr +c(nmod/nexp, nmemb/nparam, nsdates, nltime, nlevel, nlat, nlon)\cr +The ratio between the standard deviation of the members around the ensemble +mean in var_exp and the RMSE between var_exp and var_obs is output for each +experiment and each observational dataset.\cr +The p-value is provided by a one-sided Fischer test.\cr\cr +.RatioSDRMS provides the same functionality but taking a matrix of ensemble +members as input (exp). } \examples{ # Load sample data as in Load() example: @@ -64,25 +62,26 @@ rsdrms_plot <- array(dim = c(dim(rsdrms)[1:2], 4, dim(rsdrms)[4])) rsdrms_plot[, , 2, ] <- rsdrms[, , 1, ] rsdrms_plot[, , 4, ] <- rsdrms[, , 2, ] PlotVsLTime(rsdrms_plot, toptitle = "Ratio ensemble spread / RMSE", ytitle = "", - monini = 11, limits = c(-1, 1.3), listexp = c('CMIP5 IC3'), - listobs = c('ERSST'), biglab = FALSE, siglev = TRUE, - fileout = 'tos_rsdrms.eps') + monini = 11, limits = c(-1, 1.3), listexp = c('CMIP5 IC3'), + listobs = c('ERSST'), biglab = FALSE, siglev = TRUE, + fileout = 'tos_rsdrms.eps') # The following example uses veriApply combined with .RatioSDRMS instead of RatioSDRMS - \dontrun{ + \dontrun{ require(easyVerification) RatioSDRMS2 <- s2dverification:::.RatioSDRMS rsdrms2 <- veriApply("RatioSDRMS2", - sampleData$mod, - # see ?veriApply for how to use the 'parallel' option - Mean1Dim(sampleData$obs, 2), - tdim = 3, ensdim = 2) - } + sampleData$mod, + # see ?veriApply for how to use the 'parallel' option + Mean1Dim(sampleData$obs, 2), + tdim = 3, ensdim = 2) + } } \author{ History:\cr -0.1 - 2011-12 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau-manubens at ic3.cat}) - Formatting to CRAN\cr -1.1 - 2017-02 (A. Hunter, \email{alasdair.hunter at bsc.es}) - Adapted to veriApply() +0.1 - 2011-12 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau-manubens@ic3.cat}) - Formatting to CRAN\cr +1.1 - 2017-02 (A. Hunter, \email{alasdair.hunter@bsc.es}) - Adapted to veriApply() } \keyword{datagen} + diff --git a/man/Regression.Rd b/man/Regression.Rd index da4dca37fa59bae7ab33fc737abdb1700d8f9ffb..55646576e5b0c180225038f0f15230c6dfdd0243 100644 --- a/man/Regression.Rd +++ b/man/Regression.Rd @@ -1,71 +1,76 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Regression.R \name{Regression} \alias{Regression} -\title{ -Computes The Regression Of An Array On Another Along A Dimension -} -\description{ -Computes the regression of the input matrice vary on the input matrice varx along the posREG dimension by least square fitting. Provides the slope of the regression, the associated confidence interval, and the intercept.\cr -Provides also the vary data filtered out from the regression onto varx.\cr -The confidence interval relies on a student-T distribution. -} +\title{Computes The Regression Of An Array On Another Along A Dimension} \usage{ Regression(vary, varx, posREG = 2) } \arguments{ - \item{vary}{ -Array of any number of dimensions up to 10. - } - \item{varx}{ -Array of any number of dimensions up to 10. Same dimensions as vary. - } - \item{posREG}{ -Position along which to compute the regression. - } +\item{vary}{Array of any number of dimensions up to 10.} + +\item{varx}{Array of any number of dimensions up to 10. +Same dimensions as vary.} + +\item{posREG}{Position along which to compute the regression.} } \value{ - \item{$regression}{ -Array with same dimensions as varx and vary except along posREG dimension which is replaced by a length 4 dimension, corresponding to the lower limit of the 95\% confidence interval, the slope, the upper limit of the 95\% confidence interval and the intercept. - } - \item{$filtered}{ -Same dimensions as vary filtered out from the regression onto varx along the posREG dimension. - } +\item{$regression}{ + Array with same dimensions as varx and vary except along posREG + dimension which is replaced by a length 4 dimension, corresponding + to the lower limit of the 95\% confidence interval, the slope, + the upper limit of the 95\% confidence interval and the intercept. + } + \item{$filtered}{ + Same dimensions as vary filtered out from the regression onto varx + along the posREG dimension. + } +} +\description{ +Computes the regression of the input matrice vary on the input matrice varx +along the posREG dimension by least square fitting. Provides the slope of +the regression, the associated confidence interval, and the intercept.\cr +Provides also the vary data filtered out from the regression onto varx.\cr +The confidence interval relies on a student-T distribution. } \examples{ # See examples on Load() to understand the first lines in this example - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') expA <- list(name = 'experiment', path = file.path(data_path, - 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', - '$VAR_NAME$_$START_DATE$.nc')) + 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', + '$VAR_NAME$_$START_DATE$.nc')) obsX <- list(name = 'observation', path = file.path(data_path, - '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', - '$VAR_NAME$_$YEAR$$MONTH$.nc')) + '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', + '$VAR_NAME$_$YEAR$$MONTH$.nc')) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(expA), list(obsX), startDates, - output = 'lonlat', latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } - \dontshow{ + output = 'lonlat', latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } + \dontshow{ startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - output = 'lonlat', - latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } + c('observation'), startDates, + output = 'lonlat', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } sampleData$mod <- Season(sampleData$mod, 4, 11, 12, 2) sampleData$obs <- Season(sampleData$obs, 4, 11, 12, 2) reg <- Regression(Mean1Dim(sampleData$mod, 2), - Mean1Dim(sampleData$obs, 2), 2) + Mean1Dim(sampleData$obs, 2), 2) PlotEquiMap(reg$regression[1, 2, 1, , ], sampleData$lon, sampleData$lat, - toptitle='Regression of the prediction on the observations', - sizetit = 0.5) + toptitle='Regression of the prediction on the observations', + sizetit = 0.5) + } \author{ History:\cr -0.1 - 2013-05 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +0.1 - 2013-05 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{datagen} + diff --git a/man/SVD.Rd b/man/SVD.Rd index 3c157e22313012de34b05a583b131b5de53b99eb..698df95279d18f964609fc037ec947a7a53e8ad0 100644 --- a/man/SVD.Rd +++ b/man/SVD.Rd @@ -1,12 +1,64 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/SVD.R \name{SVD} \alias{SVD} -\title{ -Single Value Decomposition (Maximum Covariance Analysis) +\title{Single Value Decomposition (Maximum Covariance Analysis)} +\usage{ +SVD(vary, varx, laty = NULL, latx = NULL, nmodes = 15, corr = FALSE, + weight = TRUE) +} +\arguments{ +\item{vary}{Array containing the anomalies field for the predictor. The +expected dimensions are c(n. of time steps, n. of latitudes, n. of +longitudes).} + +\item{varx}{Array containing the anomalies field for the predictand. The +expected dimensions are c(n. of time steps, n. of latitudes, n. of +longitudes).} + +\item{laty}{Vector of latitudes of the array \code{vary}. Only required if +\code{weight = TRUE}.} + +\item{latx}{Vector of latitudes of the array \code{varx}. Only required if +\code{weight = TRUE}.} + +\item{nmodes}{Number of ECs/MCAs/modes retained and provided in the outputs.} + +\item{corr}{Whether to compute the MCA over a covariance matrix (FALSE) or +a correlation matrix (TRUE).} + +\item{weight}{Whether to apply latitude weights on the input fields or not. +TRUE by default.} +} +\value{ +\item{$SC}{ +Vector of squared covariance (n. of modes). + } + \item{$SCFs}{ + Vector of squared covariance fractions (n. of modes). + } + \item{$RUVs}{ + Vector of correlations between expansion coefficients (n. of modes). + } + \item{$ECs_U}{ + Array of expansion coefficients of predictor field (n. of time steps, + n. of modes). + } + \item{$MCAs_U}{ + Array of covariability patterns of predictor field (c(dim), n. of modes). + } + \item{$ECs_V}{ + Array of expansion coefficients of predictand field (n. of time steps, + n. of modes). + } + \item{$MCAs_V}{ + Array of covariability patterns of predictand field (c(dim), n. of modes). + } } \description{ Computes a Maximum Covariance Analysis (MCA) between vary and varx, both of dimensions c(n. of time steps, n. of latitudes, n. of longitudes), each -over a region of interest, e.g.: prlr over Europe and tos over North Atlantic. +over a region of interest, e.g.: prlr over Europe and tos over North Atlantic. The input fields are latitude-weighted by default (can be adjustable via \code{weight}).\cr Returns a vector of squared covariance fraction (SCFs) explained by @@ -19,104 +71,50 @@ and its expansion coefficient.\cr The MCA is computed by default with the covariance matrix. It can be computed with the correlation matrix by setting \code{corr = TRUE}. } -\usage{ -SVD(vary, varx, laty = NULL, latx = NULL, nmodes = 15, corr = FALSE, - weight = TRUE) -} -\arguments{ - \item{vary}{ -Array containing the anomalies field for the predictor. The expected -dimensions are c(n. of time steps, n. of latitudes, n. of longitudes). - } - \item{varx}{ -Array containing the anomalies field for the predictand. The expected -dimensions are c(n. of time steps, n. of latitudes, n. of longitudes). - } - \item{laty}{ -Vector of latitudes of the array \code{vary}. Only required if -\code{weight = TRUE}. - } - \item{latx}{ -Vector of latitudes of the array \code{varx}. Only required if -\code{weight = TRUE}. - } - \item{nmodes}{ -Number of ECs/MCAs/modes retained and provided in the outputs. - } - \item{corr}{ -Whether to compute the MCA over a covariance matrix (FALSE) or a correlation -matrix (TRUE). - } - \item{weight}{ -Whether to apply latitude weights on the input fields or not. TRUE by -default. - } -} -\value{ - \item{$SC}{ -Vector of squared covariance (n. of modes). - } - \item{$SCFs}{ -Vector of squared covariance fractions (n. of modes). - } - \item{$RUVs}{ -Vector of correlations between expansion coefficients (n. of modes). - } - \item{$ECs_U}{ -Array of expansion coefficients of predictor field (n. of time steps, n. of modes). - } - \item{$MCAs_U}{ -Array of covariability patterns of predictor field (c(dim), n. of modes). - } - \item{$ECs_V}{ -Array of expansion coefficients of predictand field (n. of time steps, n. of modes). - } - \item{$MCAs_V}{ -Array of covariability patterns of predictand field (c(dim), n. of modes). - } -} \examples{ # See examples on Load() to understand the first lines in this example - \dontrun{ + \dontrun{ data_path <- system.file('sample_data', package = 's2dverification') expA <- list(name = 'experiment', path = file.path(data_path, - 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', - '$VAR_NAME$_$START_DATE$.nc')) + 'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly', + '$VAR_NAME$_$START_DATE$.nc')) obsX <- list(name = 'observation', path = file.path(data_path, - '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', - '$VAR_NAME$_$YEAR$$MONTH$.nc')) + '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$', + '$VAR_NAME$_$YEAR$$MONTH$.nc')) # Now we are ready to use Load(). startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- Load('tos', list(expA), list(obsX), startDates, - leadtimemin = 1, leadtimemax = 4, output = 'lonlat', - latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) - } - \dontshow{ + leadtimemin = 1, leadtimemax = 4, output = 'lonlat', + latmin = 27, latmax = 48, lonmin = -12, lonmax = 40) + } + \dontshow{ startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101') sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'), - c('observation'), startDates, - leadtimemin = 1, - leadtimemax = 4, - output = 'lonlat', - latmin = 27, latmax = 48, - lonmin = -12, lonmax = 40) - } + c('observation'), startDates, + leadtimemin = 1, + leadtimemax = 4, + output = 'lonlat', + latmin = 27, latmax = 48, + lonmin = -12, lonmax = 40) + } # This example computes the ECs and MCAs along forecast horizons and plots the # one that explains the greatest amount of variability. The example data is # very low resolution so it does not make a lot of sense. ano <- Ano_CrossValid(sampleData$mod, sampleData$obs) mca <- SVD(Mean1Dim(ano$ano_exp, 2)[1, , 1, , ], - Mean1Dim(ano$ano_obs, 2)[1, , 1, , ], - sampleData$lat, sampleData$lat) + Mean1Dim(ano$ano_obs, 2)[1, , 1, , ], + sampleData$lat, sampleData$lat) PlotEquiMap(mca$MCAs_U[1, , ], sampleData$lon, sampleData$lat) plot(mca$ECs_U[1, ]) PlotEquiMap(mca$MCAs_V[1, , ], sampleData$lon, sampleData$lat) plot(mca$ECs_V[1, ]) + } \author{ History:\cr -0.1 - 2010-09 (J.-G. Serrano, \email{javier.garcia at bsc.es}) - Original code\cr -1.0 - 2016-04 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Formatting to R CRAN +0.1 - 2010-09 (J.-G. Serrano, \email{javier.garcia@bsc.es}) - Original code\cr +1.0 - 2016-04 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Formatting to R CRAN } \keyword{datagen} + diff --git a/man/Season.Rd b/man/Season.Rd index aa143e27366238a89d12610ad4d300ddd05d1bc7..08487256eea4cb2072078adbc9cdaf1e7b1158fd 100644 --- a/man/Season.Rd +++ b/man/Season.Rd @@ -1,33 +1,35 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Season.R \name{Season} \alias{Season} -\title{ -Computes Seasonal Means -} -\description{ -Computes seasonal means on timeseries organized in a array of any number of dimensions up to 10 dimensions where the time dimension is one of those 10 dimensions. -} +\title{Computes Seasonal Means} \usage{ Season(var, posdim = 4, monini, moninf, monsup) } \arguments{ - \item{var}{ -Array containing the timeseries along one of its dimensions. - } - \item{posdim}{ -Dimension along which to compute seasonal means = Time dimension - } - \item{monini}{ -First month of the time series: 1 to 12. - } - \item{moninf}{ -Month when to start the seasonal means: 1 to 12. - } - \item{monsup}{ -Month when to stop the seasonal means: 1 to 12. - } +\item{var}{Array containing the timeseries along one of its dimensions.} + +\item{posdim}{Dimension along which to compute seasonal means = Time +dimension.} + +\item{monini}{an integer indicating the first month of the time series: 1 to +12.} + +\item{moninf}{an integer indicating the month when to start the seasonal +means: 1 to 12.} + +\item{monsup}{an integer indicating the month when to stop the seasonal +means: 1 to 12.} } \value{ -Array with the same dimensions as var except along the posdim dimension whose length corresponds to the number of seasons. Partial seasons are not accounted for. +Array with the same dimensions as var except along the posdim + dimension whose length corresponds to the number of seasons. Partial + seasons are not accounted for. +} +\description{ +Computes seasonal means on timeseries organized in a array of any number of +dimensions up to 10 dimensions where the time dimension is one of those 10 +dimensions. } \examples{ # Load sample data as in Load() example: @@ -37,16 +39,17 @@ initial_month <- 11 mean_start_month <- 12 mean_stop_month <- 2 season_means_mod <- Season(sampleData$mod, leadtimes_dimension, initial_month, - mean_start_month, mean_stop_month) + mean_start_month, mean_stop_month) season_means_obs <- Season(sampleData$obs, leadtimes_dimension, initial_month, - mean_start_month, mean_stop_month) + mean_start_month, mean_stop_month) PlotAno(season_means_mod, season_means_obs, startDates, - toptitle = paste('winter (DJF) temperatures'), ytitle = c('K'), - legends = 'ERSST', biglab = FALSE, fileout = 'tos_season_means.eps') + toptitle = paste('winter (DJF) temperatures'), ytitle = c('K'), + legends = 'ERSST', biglab = FALSE, fileout = 'tos_season_means.eps') } \author{ History:\cr -0.1 - 2011-03 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{datagen} + diff --git a/man/SelIndices.Rd b/man/SelIndices.Rd index b6b1795f988172037ca423a5e0e97a9870464bfa..dbf34da2a73fd7f756eded28a3b00df186d777bb 100644 --- a/man/SelIndices.Rd +++ b/man/SelIndices.Rd @@ -1,28 +1,27 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/SelIndices.R \name{SelIndices} \alias{SelIndices} -\title{ -Slices A Matrix Along A Dimension -} -\description{ -This function selects a subset of ensemble members from an array containing any number of dimensions. -} +\title{Slices A Matrix Along A Dimension} \usage{ SelIndices(var, posdim, limits) } \arguments{ - \item{var}{ -An array with any number of dimensions. - } - \item{posdim}{ -The dimension along which the ensemble subset should be selected. - } - \item{limits}{ -The lower and upper limits for the selection of ensemble members along the posdim dimension. - } +\item{var}{An array with any number of dimensions.} + +\item{posdim}{The dimension along which the ensemble subset should be +selected.} + +\item{limits}{The lower and upper limits for the selection of ensemble +members along the posdim dimension.} } \value{ The subsetted array. } +\description{ +This function selects a subset of ensemble members from an array containing +any number of dimensions. +} \examples{ a <- array(rnorm(24), dim = c(2, 3, 4, 1)) print(a) @@ -30,10 +29,12 @@ print(a[, , 2:3, ]) print(dim(a[, , 2:3, ])) print(SelIndices(a, 3, c(2, 3))) print(dim(SelIndices(a, 3, c(2, 3)))) + } \author{ History:\cr -0.1 - 2011-04 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +0.1 - 2011-04 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{datagen} + diff --git a/man/Smoothing.Rd b/man/Smoothing.Rd index 841fb0526f786d56fd96e87d9f9c8d796e0e7b3a..77a23cc996ee0c0f5f6ad8469da529f119c4af05 100644 --- a/man/Smoothing.Rd +++ b/man/Smoothing.Rd @@ -1,27 +1,26 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Smoothing.R \name{Smoothing} \alias{Smoothing} -\title{ -Smoothes An Array Along A Dimension -} -\description{ -Smoothes an array of any number of dimensions along one of its dimensions -} +\title{Smoothes An Array Along A Dimension} \usage{ Smoothing(var, runmeanlen = 12, numdimt = 4) } \arguments{ - \item{var}{ -Array to be smoothed along one of its dimension (typically the forecast time dimension). - } - \item{runmeanlen}{ -Running mean length in number of sampling units (typically months). - } - \item{numdimt}{ -Dimension to smooth. - } +\item{var}{Array to be smoothed along one of its dimension (typically the +forecast time dimension).} + +\item{runmeanlen}{Running mean length in number of sampling units +(typically months).} + +\item{numdimt}{Dimension to smooth.} } \value{ -Array with same the dimensions as 'var' but smoothed along the 'numdimt'-th dimension. +Array with same the dimensions as 'var' but smoothed along the + 'numdimt'-th dimension. +} +\description{ +Smoothes an array of any number of dimensions along one of its dimensions. } \examples{ # Load sample data as in Load() example: @@ -34,14 +33,16 @@ dim_to_smooth <- 4 # Smooth along lead-times smooth_ano_exp <- Smoothing(ano_exp, runmean_months, dim_to_smooth) smooth_ano_obs <- Smoothing(ano_obs, runmean_months, dim_to_smooth) PlotAno(smooth_ano_exp, smooth_ano_obs, startDates, - toptitle = "Smoothed Mediterranean mean SST", ytitle = "K", - fileout = "tos_smoothed_ano.eps") + toptitle = "Smoothed Mediterranean mean SST", ytitle = "K", + fileout = "tos_smoothed_ano.eps") } \author{ History:\cr -0.1 - 2011-03 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to R CRAN -1.1 - 2015-05 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Adding -security checks, fixing computation in cases where runmeanlen is odd and making it able to work on arrays of any number of dimensions. +0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to R CRAN\cr +1.1 - 2015-05 (N. Manubens, \email{nicolau.manubens@bsc.es}) - Adding + security checks, fixing computation in cases where runmeanlen is odd and + making it able to work on arrays of any number of dimensions. } \keyword{datagen} + diff --git a/man/Spectrum.Rd b/man/Spectrum.Rd index eda82779bb128bc1777ba7e9444a91fdf3ed0e16..cd2dad7a269fb4e395bd199946c0647bb04ef7e0 100644 --- a/man/Spectrum.Rd +++ b/man/Spectrum.Rd @@ -1,35 +1,49 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Spectrum.R \name{Spectrum} \alias{Spectrum} \title{Estimates Frequency Spectrum} -\description{ -This function estimates the frequency spectrum of the xdata array together with its 95\% and 99\% significance level. The output is provided as an array with dimensions c(number of frequencies, 4). The column contains the frequency values, the power, the 95\% significance level and the 99\% one.\cr -The spectrum estimation relies on a R built-in function and the significance levels are estimated by a Monte-Carlo method. +\usage{ +Spectrum(xdata) } -\usage{Spectrum(xdata)} \arguments{ - \item{xdata}{Array of which the frequency spectrum is required} +\item{xdata}{Array of which the frequency spectrum is required.} +} +\value{ +Frequency spectrum with dimensions c(number of frequencies, 4). The + column contains the frequency values, the power, the 95\% significance + level and the 99\% one. +} +\description{ +This function estimates the frequency spectrum of the xdata array together +with its 95\% and 99\% significance level. The output is provided as an +array with dimensions c(number of frequencies, 4). The column contains the +frequency values, the power, the 95\% significance level and the 99\% one.\cr +The spectrum estimation relies on a R built-in function and the significance +levels are estimated by a Monte-Carlo method. } -\value{Frequency spectrum with dimensions c(number of frequencies, 4). The column contains the frequency values, the power, the 95\% significance level and the 99\% one.} \examples{ # Load sample data as in Load() example: example(Load) ensmod <- Mean1Dim(sampleData$mod, 2) for (jstartdate in 1:3) { - spectrum <- Spectrum(ensmod[1, jstartdate, ]) - for (jlen in 1:dim(spectrum)[1]) { - if (spectrum[jlen, 2] > spectrum[jlen, 4]) { - ensmod[1, jstartdate, ] <- Filter(ensmod[1, jstartdate, ], - spectrum[jlen, 1]) - } - } + spectrum <- Spectrum(ensmod[1, jstartdate, ]) + for (jlen in 1:dim(spectrum)[1]) { + if (spectrum[jlen, 2] > spectrum[jlen, 4]) { + ensmod[1, jstartdate, ] <- Filter(ensmod[1, jstartdate, ], + spectrum[jlen, 1]) + } + } } PlotAno(InsertDim(ensmod, 2, 1), sdates = startDates, fileout = - 'filtered_ensemble_mean.eps') + 'filtered_ensemble_mean.eps') + } \author{ History:\cr -0.1 - 2012-02 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +0.1 - 2012-02 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{datagen} + diff --git a/man/Spread.Rd b/man/Spread.Rd index 2d9007cc89c8ba8f7bada64375764b1ef4736c84..bc14fa7a0d58fcc04859105b48e453c73b5d4c6a 100644 --- a/man/Spread.Rd +++ b/man/Spread.Rd @@ -1,52 +1,59 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Spread.R \name{Spread} \alias{Spread} -\title{ -Computes InterQuartile Range, Maximum-Minimum, Standard Deviation and Median Absolute Deviation of the Ensemble Members -} -\description{ -Computes the InterQuartile Range, the Maximum minus Mininum, the Standard Deviation and the Median Absolute Deviation along the list of dimensions provided by the posdim argument (typically along the ensemble member and start date dimension).\cr -The confidence interval is optionally computed by bootstrapping. -} +\title{Computes InterQuartile Range, Maximum-Minimum, Standard Deviation and +Median Absolute Deviation of the Ensemble Members} \usage{ Spread(var, posdim = 2, narm = TRUE, siglev = 0.95, conf = TRUE) } \arguments{ - \item{var}{ -Matrix of any number of dimensions up to 10. - } - \item{posdim}{ -List of dimensions along which to compute IQR/MaxMin/SD/MAD. - } - \item{narm}{ -TRUE/FALSE if NA removed/kept for computation. Default = TRUE. - } - \item{siglev}{ -Confidence level of the computed confidence interval. 0.95 by default. - } - \item{conf}{ -Whether to compute the confidence intervals or not. TRUE by default. - } -} -\details{ -Example: --------- -To compute IQR, Max-Min, SD & MAD accross the members and start dates of var output from \code{Load()} or \code{Ano()} or \code{Ano_CrossValid()}, call:\cr - spread(var, posdim = c(2, 3), narm = TRUE) +\item{var}{Matrix of any number of dimensions up to 10.} + +\item{posdim}{List of dimensions along which to compute IQR/MaxMin/SD/MAD.} + +\item{narm}{TRUE/FALSE if NA removed/kept for computation. Default = TRUE.} + +\item{siglev}{Confidence level of the computed confidence interval. +0.95 by default.} + +\item{conf}{Whether to compute the confidence intervals or not. +TRUE by default.} } \value{ -Matrix with the same dimensions as var except along the first posdim dimension which is replaced by a length 1 or 3 dimension, corresponding to the lower limit of the \code{siglev}\% confidence interval (only present if \code{conf = TRUE}), the spread, and the upper limit of the \code{siglev}\% confidence interval (only present if \code{conf = TRUE}) for each experiment/leadtime/latitude/longitude. - \item{$iqr}{ -InterQuartile Range. - } - \item{$maxmin}{ -Maximum - Minimum. - } - \item{$sd}{ -Standard Deviation. - } - \item{$mad}{ -Median Absolute Deviation. - } +Matrix with the same dimensions as var except along the first posdim +dimension which is replaced by a length 1 or 3 dimension, corresponding to +the lower limit of the \code{siglev}\% confidence interval +(only present if \code{conf = TRUE}), the spread, and the upper limit of +the \code{siglev}\% confidence interval (only present if \code{conf = TRUE}) +for each experiment/leadtime/latitude/longitude. + \item{$iqr}{ + InterQuartile Range. + } + \item{$maxmin}{ + Maximum - Minimum. + } + \item{$sd}{ + Standard Deviation. + } + \item{$mad}{ + Median Absolute Deviation. + } +} +\description{ +Computes the InterQuartile Range, the Maximum minus Mininum, the Standard +Deviation and the Median Absolute Deviation along the list of dimensions +provided by the posdim argument (typically along the ensemble member and +start date dimension).\cr +The confidence interval is optionally computed by bootstrapping. +} +\details{ +Example:\cr +--------\cr +To compute IQR, Max-Min, SD & MAD accross the members and start dates of +var output from \code{Load()} or \code{Ano()} or \code{Ano_CrossValid()}, +call:\cr + spread(var, posdim = c(2, 3), narm = TRUE) } \examples{ # Load sample data as in Load() example: @@ -57,29 +64,31 @@ runmean_months <- 12 dim_to_smooth <- 4 # Smooth along lead-times smooth_ano_exp <- Smoothing(ano_exp, runmean_months, dim_to_smooth) smooth_ano_exp_m_sub <- smooth_ano_exp - InsertDim(Mean1Dim(smooth_ano_exp, 2, - narm = TRUE), 2, dim(smooth_ano_exp)[2]) + narm = TRUE), 2, dim(smooth_ano_exp)[2]) spread <- Spread(smooth_ano_exp_m_sub, c(2, 3)) PlotVsLTime(spread$iqr, - toptitle = "Inter-Quartile Range between ensemble members", - ytitle = "K", monini = 11, limits = NULL, - listexp = c('CMIP5 IC3'), listobs = c('ERSST'), biglab = FALSE, - hlines = c(0), fileout = 'tos_iqr.eps') + toptitle = "Inter-Quartile Range between ensemble members", + ytitle = "K", monini = 11, limits = NULL, + listexp = c('CMIP5 IC3'), listobs = c('ERSST'), biglab = FALSE, + hlines = c(0), fileout = 'tos_iqr.eps') PlotVsLTime(spread$maxmin, toptitle = "Maximum minus minimum of the members", - ytitle = "K", monini = 11, limits = NULL, - listexp = c('CMIP5 IC3'), listobs = c('ERSST'), biglab = FALSE, - hlines = c(0), fileout = 'tos_maxmin.eps') + ytitle = "K", monini = 11, limits = NULL, + listexp = c('CMIP5 IC3'), listobs = c('ERSST'), biglab = FALSE, + hlines = c(0), fileout = 'tos_maxmin.eps') PlotVsLTime(spread$sd, toptitle = "Standard deviation of the members", - ytitle = "K", monini = 11, limits = NULL, - listexp = c('CMIP5 IC3'), listobs = c('ERSST'), biglab = FALSE, - hlines = c(0), fileout = 'tos_sd.eps') + ytitle = "K", monini = 11, limits = NULL, + listexp = c('CMIP5 IC3'), listobs = c('ERSST'), biglab = FALSE, + hlines = c(0), fileout = 'tos_sd.eps') PlotVsLTime(spread$mad, toptitle = "Median Absolute Deviation of the members", - ytitle = "K", monini = 11, limits = NULL, - listexp = c('CMIP5 IC3'), listobs = c('ERSST'), biglab = FALSE, - hlines = c(0), fileout = 'tos_mad.eps') + ytitle = "K", monini = 11, limits = NULL, + listexp = c('CMIP5 IC3'), listobs = c('ERSST'), biglab = FALSE, + hlines = c(0), fileout = 'tos_mad.eps') + } \author{ History:\cr -0.1 - 2011-03 (V. Guemas, \email{virginie.guemas at ic3.cat}) - Original code\cr -1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens at ic3.cat}) - Formatting to CRAN +0.1 - 2011-03 (V. Guemas, \email{virginie.guemas@ic3.cat}) - Original code\cr +1.0 - 2013-09 (N. Manubens, \email{nicolau.manubens@ic3.cat}) - Formatting to CRAN } \keyword{datagen} + diff --git a/man/StatSeasAtlHurr.Rd b/man/StatSeasAtlHurr.Rd index e2ad65a712a011450d1538658230a60f9ab7dcdf..9822eb907ff56ae7f2298336d22cd1b902bcff14 100644 --- a/man/StatSeasAtlHurr.Rd +++ b/man/StatSeasAtlHurr.Rd @@ -1,73 +1,85 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/StatSeasAtlHurr.R \name{StatSeasAtlHurr} \alias{StatSeasAtlHurr} \title{Compute estimate of seasonal mean of Atlantic hurricane activity} -\description{ -Compute one of G. Villarini's statistically downscaled measure of mean Atlantic hurricane activity and its variance. The hurricane activity is estimated using seasonal averages of sea surface temperature anomalies over the tropical Atlantic (bounded by 10N-25N and 80W-20W) and the tropics at large (bounded by 30N-30S). The anomalies are for the JJASON season.\cr -The estimated seasonal average is either 1) number of hurricanes, 2) number of tropical cyclones with lifetime >=48h or 3) power dissipation index (PDI; in 10^11 m^3 s^{-2}).\cr -The statistical models used in this function are described in\cr -} \usage{ -StatSeasAtlHurr(atlano = NULL, tropano = NULL, hrvar = 'HR') +StatSeasAtlHurr(atlano = NULL, tropano = NULL, hrvar = "HR") } \arguments{ - \item{atlano}{ -Array of Atlantic sea surface temperature anomalies. Must have the same dimension as tropano. - } - \item{tropano}{ -Array of tropical sea surface temperature anomalies. Must have the same dimension as atlano. - } - \item{hrvar}{ -The seasonal average to be estimated. The options are either\cr +\item{atlano}{Array of Atlantic sea surface temperature anomalies. +Must have the same dimension as tropano.} + +\item{tropano}{Array of tropical sea surface temperature anomalies. +Must have the same dimension as atlano.} + +\item{hrvar}{The seasonal average to be estimated. The options are either\cr "HR" (hurricanes) \cr "TC" (tropical cyclones with lifetime >=48h) \cr -"PDI" (power dissipation index) \cr - } +"PDI" (power dissipation index) \cr} } \value{ A list composed of two matrices:\cr - \itemize{ - \item{ -1. a matrix (mean) with the seasonal average values of the desired quantity.\cr - } - \item{ -2. a matrix (var) of the variance of that quantity.\cr - } - } -The dimensions of the two matrices are the same as the dimensions of atlano/tropano. +\enumerate{ + \item{ + A matrix (mean) with the seasonal average values of the desired quantity.\cr + } + \item{ + A matrix (var) of the variance of that quantity.\cr + } +} +The dimensions of the two matrices are the same as the dimensions of + atlano/tropano. +} +\description{ +Compute one of G. Villarini's statistically downscaled measure of mean +Atlantic hurricane activity and its variance. The hurricane activity is +estimated using seasonal averages of sea surface temperature anomalies over +the tropical Atlantic (bounded by 10N-25N and 80W-20W) and the tropics at +large (bounded by 30N-30S). The anomalies are for the JJASON season.\cr +The estimated seasonal average is either 1) number of hurricanes, 2) number +of tropical cyclones with lifetime >=48h or 3) power dissipation index +(PDI; in 10^11 m^3 s^{-2}).\cr +The statistical models used in this function are described in\cr } \examples{ # Let AtlAno represents 5 different 5-year forecasts of seasonally averaged # Atlantic sea surface temperature anomalies. AtlAno <- matrix(c(-0.31, -0.36, 0.26, -0.16, -0.16, - -0.06, -0.22, -0.31, -0.36, -0.39, - 0.20, -0.14, 0.12, 0.22, 0.02, - -0.28, 0.26, -0.10, 0.18, 0.33, - 0.45, 0.46, 0.04, 0.12, 0.21), - nrow = 5, ncol = 5) + -0.06, -0.22, -0.31, -0.36, -0.39, + 0.20, -0.14, 0.12, 0.22, 0.02, + -0.28, 0.26, -0.10, 0.18, 0.33, + 0.45, 0.46, 0.04, 0.12, 0.21), + nrow = 5, ncol = 5) # Let TropAno represents 5 corresponding 5-year forecasts of seasonally averaged # tropical sea surface temperature anomalies. TropAno <- matrix(c(-0.22, -.13, 0.07, -0.16, -0.15, - 0.00, -0.03, -0.22, -0.13, -0.10, - 0.07, -0.07, 0.17, 0.10, -0.15, - -0.01, 0.08, 0.07, 0.17, 0.13, - 0.16, 0.15, -0.09, 0.03, 0.27), - nrow = 5, ncol = 5) + 0.00, -0.03, -0.22, -0.13, -0.10, + 0.07, -0.07, 0.17, 0.10, -0.15, + -0.01, 0.08, 0.07, 0.17, 0.13, + 0.16, 0.15, -0.09, 0.03, 0.27), + nrow = 5, ncol = 5) # The seasonal average of hurricanes for each of the five forecasted years, # for each forecast, would then be given by hr_count <- StatSeasAtlHurr(atlano = AtlAno, - tropano = TropAno, - hrvar = 'HR') + tropano = TropAno, + hrvar = 'HR') print(hr_count$mean) -} + +} +\author{ +History:\cr +0.1 - 2015-11 (Louis-Philippe Caron, \email{louis-philippe.caron@bsc.es}) - Original code +} \references{ Villarini et al. (2010) Mon Wea Rev, 138, 2681-2705.\cr Villarini et al. (2012) Mon Wea Rev, 140, 44-65.\cr Villarini et al. (2012) J Clim, 25, 625-637.\cr -An example of how the function can be used in hurricane forecast studies is given in\cr -Caron, L.-P. et al. (2014) Multi-year prediction skill of Atlantic hurricane activity in CMIP5 decadal hindcasts. Climate Dynamics, 42, 2675-2690. doi:10.1007/s00382-013-1773-1. -} - \author{ -History:\cr -0.1 - 2015-11 (Louis-Philippe Caron, \email{louis-philippe.caron@bsc.es}) - Original code +An example of how the function can be used in hurricane forecast studies + is given in\cr +Caron, L.-P. et al. (2014) Multi-year prediction skill of Atlantic hurricane + activity in CMIP5 decadal hindcasts. Climate Dynamics, 42, 2675-2690. + doi:10.1007/s00382-013-1773-1. } \keyword{datagen} + diff --git a/man/Subset.Rd b/man/Subset.Rd index 2c883ffa771e0330d97dfa3a47dc65a7ac1c3411..4e52c6db150748c68db88419d162c5db884d1046 100644 --- a/man/Subset.Rd +++ b/man/Subset.Rd @@ -1,13 +1,34 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Subset.R \name{Subset} \alias{Subset} \title{Subset a Data Array} +\usage{ +Subset(x, along, indices, drop = FALSE) +} +\arguments{ +\item{x}{A multidimensional array to be sliced. It can have dimension names +either in \code{names(dim(x))} or either in the attribute 'dimensions'.} + +\item{along}{Vector with references to the dimensions to take the subset +from: either integers or dimension names.} + +\item{indices}{List of indices to take from each dimension specified in +'along'. If a single dimension is specified in 'along' the indices can be +directly provided as a single integer or as a vector.} + +\item{drop}{Whether to drop all the dimensions of length 1 in the resulting +array, none, only those that are specified in 'along', or only those that +are not specified in 'along'. The possible values are, respectively: 'all' +or TRUE, 'none' or FALSE, 'selected', and 'non-selected'.} +} \description{ This function allows to subset (i.e. slice, take a chunk of) an array, in a similar way as done in the function \code{take()} in the package plyr. There are two main inprovements:\cr\cr The input array can have dimension names, either -in \code{names(dim(x))} or in the attribute 'dimensions', and the dimensions to -subset along can be specified via the parameter \code{along} either with +in \code{names(dim(x))} or in the attribute 'dimensions', and the dimensions +to subset along can be specified via the parameter \code{along} either with integer indices or either by their name.\cr\cr There are additional ways to adjust which dimensions are dropped in the resulting array: either to drop all, to drop none, to drop only the ones that @@ -15,35 +36,13 @@ have been sliced or to drop only the ones that have not been sliced.\cr\cr If an array is provided without dimension names, dimension names taken from the parameter \code{dim_names} will be added to the array. } -\usage{ -Subset(x, along, indices, drop = FALSE) -} -\arguments{ - \item{x}{ -A multidimensional array to be sliced. It can have dimension names either -in \code{names(dim(x))} or either in the attribute 'dimensions'. - } - \item{along}{ -Vector with references to the dimensions to take the subset from: either -integers or dimension names. - } - \item{indices}{ -List of indices to take from each dimension specified in 'along'. If a single -dimension is specified in 'along' the indices can be directly provided as a -single integer or as a vector. - } - \item{drop}{ -Whether to drop all the dimensions of length 1 in the resulting array, none, -only those that are specified in 'along', or only those that are not specified -in 'along'. The possible values are, respectively: 'all' or TRUE, 'none' or -FALSE, 'selected', and 'non-selected'. - } -} \examples{ subset <- Subset(sampleMap$mod, c('dataset', 'sdate', 'ftime'), - list(1, 1, 1), drop = 'selected') + list(1, 1, 1), drop = 'selected') PlotLayout(PlotEquiMap, c('lat', 'lon'), subset, - sampleMap$lon, sampleMap$lat, - titles = paste('Member', 1:3)) + sampleMap$lon, sampleMap$lat, + titles = paste('Member', 1:3)) + } \keyword{dplot} + diff --git a/man/ToyModel.Rd b/man/ToyModel.Rd index bfbd179e3c8b01748c07def255e076479dfca5e3..da07596095086e4ef17463aa8c33b44902ea3e6a 100644 --- a/man/ToyModel.Rd +++ b/man/ToyModel.Rd @@ -1,10 +1,57 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ToyModel.R \name{ToyModel} \alias{ToyModel} -\title{ -Synthetic forecast generator imitating seasonal to decadal forecasts. The -components of a forecast: (1) predictabiltiy (2) forecast error (3) non-stationarity -and (4) ensemble generation. The forecast can be computed for real observations or -observations generated artifically. +\title{Synthetic forecast generator imitating seasonal to decadal forecasts. The +components of a forecast: (1) predictabiltiy (2) forecast error (3) +non-stationarity and (4) ensemble generation. The forecast can be computed +for real observations or observations generated artifically.} +\usage{ +ToyModel(alpha = 0.1, beta = 0.4, gamma = 1, sig = 1, trend = 0, + nstartd = 30, nleadt = 4, nmemb = 10, obsini = NULL, fxerr = NULL) +} +\arguments{ +\item{alpha}{Predicabiltiy of the forecast on the observed residuals +Must be a scalar 0 < alpha < 1.} + +\item{beta}{Standard deviation of forecast error +Must be a scalar 0 < beta < 1.} + +\item{gamma}{Factor on the linear trend to sample model uncertainty. Can be +a scalar or a vector of scalars -inf < gammay < inf. +Defining a scalar results in multiple forecast, corresponding to different +models with different trends.} + +\item{sig}{Standard deviation of the residual variability of the forecast. +If observations are provided 'sig' is computed from the observations.} + +\item{trend}{Linear trend of the forecast. The same trend is used for each +lead-time. If observations are provided the 'trend' is computed from the +observations, with potentially different trends for each lead-time. The +trend has no unit and needs to be defined according to the time vector +[1,2,3,... nstartd].} + +\item{nstartd}{Number of start-dates of the forecast. +If observations are provided the 'nstartd' is computed from the observations.} + +\item{nleadt}{Number of lead-times of the forecats. +If observations are provided the 'nleadt' is computed from the observations.} + +\item{nmemb}{Number of members of the forecasts.} + +\item{obsini}{Observations that can be used in the synthetic forecast coming +from Load (anomalies are expected). If no observations are provided +artifical observations are generated based on Gaussian variaiblity with +standard deviation from 'sig' and linear trend from 'trend'.} + +\item{fxerr}{Provides a fixed error of the forecast instead of generating +one from the level of beta. This allows to perform pair of forecasts with +the same conditional error as required for instance in an attribution context.} +} +\value{ +List of forecast with $mod including the forecast and $obs the + observations. The dimensions correspond to + c(length(gamma), nmemb, nstartd, nleadt) } \description{ The toymodel is based on the model presented in Weigel et al. (2008) QJRS @@ -18,64 +65,6 @@ ensemble members. It imitates components of a forecast: (1) predictabiltiy The forecast can be computed for real observations or observations generated artifically. } -\usage{ -ToyModel(alpha = 0.1, beta = 0.4, gamma = 1, sig = 1, trend = 0, - nstartd = 30, nleadt = 4, nmemb = 10, obsini = NULL, - fxerr = NULL) -} -\arguments{ - \item{alpha}{ -Predicabiltiy of the forecast on the observed residuals -Must be a scalar 0