From 5d2d550c85db8965e790971e9284156b347a1fb8 Mon Sep 17 00:00:00 2001 From: aho Date: Tue, 3 Sep 2019 15:43:26 +0200 Subject: [PATCH] Revert "Merge branch 'develop-trend-doc' into 'master'" This reverts merge request !183 --- NAMESPACE | 1 - R/PlotMatrix.R | 201 ---------------------------------------------- R/Trend.R | 46 +++++------ man/PlotMatrix.Rd | 89 -------------------- man/Trend.Rd | 46 +++++------ 5 files changed, 42 insertions(+), 341 deletions(-) delete mode 100644 R/PlotMatrix.R delete mode 100644 man/PlotMatrix.Rd diff --git a/NAMESPACE b/NAMESPACE index 4e855789..3e35710e 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -56,7 +56,6 @@ export(PlotBoxWhisker) export(PlotClim) export(PlotEquiMap) export(PlotLayout) -export(PlotMatrix) export(PlotSection) export(PlotStereoMap) export(PlotVsLTime) diff --git a/R/PlotMatrix.R b/R/PlotMatrix.R deleted file mode 100644 index 32a40c99..00000000 --- a/R/PlotMatrix.R +++ /dev/null @@ -1,201 +0,0 @@ -#'Function to convert any numerical table to a grid of coloured squares. -#' -#'This function converts a numerical data matrix into a coloured -#'grid. It is useful for a slide or article to present tabular results as -#'colors instead of numbers. -#' -#'@param var A numerical matrix containing the values to be displayed in a -#' colored image. -#'@param brks A vector of the color bar intervals. The length must be one more -#' than the parameter 'cols'. Use ColorBar() to generate default values. -#'@param cols A vector of valid color identifiers for color bar. The length -#' must be one less than the parameter 'brks'. Use ColorBar() to generate -#' default values. -#'@param toptitle A string of the title of the grid. Set NULL as default. -#'@param title.color A string of valid color identifier to decide the title -#' color. Set "royalblue4" as default. -#'@param xtitle A string of title of the x-axis. Set NULL as default. -#'@param ytitle A string of title of the y-axis. Set NULL as default. -#'@param xlabels A vector of labels of the x-axis. The length must be -#' length of the column of parameter 'var'. Set the sequence from 1 to the -#' length of the column of parameter 'var' as default. -#'@param xvert A logical value to decide whether to place x-axis labels -#' vertically. Set FALSE as default, which keeps the labels horizontally. -#'@param ylabels A vector of labels of the y-axis The length must be -#' length of the row of parameter 'var'. Set the sequence from 1 to the -#' length of the row of parameter 'var' as default. -#'@param line An integer specifying the distance between the title of the -#' x-axis and the x-axis. Set 3 as default. Adjust if the x-axis labels -#' are long. -#'@param figure.width A positive number as a ratio adjusting the width of the -#' grids. Set 1 as default. -#'@param legend A logical value to decide to draw the grid color legend or not. -#' Set TRUE as default. -#'@param legend.width A number between 0 and 0.5 to adjust the legend width. -#' Set 0.15 as default. -#'@param fileout A string of full directory path and file name indicating where -#' to save the plot. If not specified (default), a graphics device will pop up. -#'@param size_units A string indicating the units of the size of the device -#' (file or window) to plot in. Set 'px' as default. See ?Devices and the -#' creator function of the corresponding device. -#'@param res A positive number indicating resolution of the device (file or window) -#' to plot in. See ?Devices and the creator function of the corresponding device. -#'@param ... The additional parameters to be passed to function ColorBar() in -#' s2dverification for color legend creation. -#'@return A figure in popup window by default, or saved to the specified path. -#' -#'@examples -#'#Example with random data -#' PlotMatrix(var = matrix(rnorm(n = 120, mean = 0.3), 10, 12), -#' cols = c('white','#fef0d9','#fdd49e','#fdbb84','#fc8d59', -#' '#e34a33','#b30000', '#7f0000'), -#' brks = c(-1, 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 1), -#' toptitle = "Mean Absolute Error", -#' xtitle = "Forecast time (month)", ytitle = "Start date", -#' xlabels = c("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", -#' "Aug", "Sep", "Oct", "Nov", "Dec")) -#'@importFrom grDevices dev.new dev.off dev.cur -#'@export -PlotMatrix <- function(var, brks = NULL, cols = NULL, - toptitle = NULL, title.color = "royalblue4", - xtitle = NULL, ytitle = NULL, xlabels = NULL, xvert = FALSE, - ylabels = NULL, line = 3, figure.width = 1, legend = TRUE, - legend.width = 0.15, fileout = NULL, - size_units = 'px', res = 100, ...) { - - # Check variables: - if (!is.matrix(var)) - stop("Input values are not a matrix") - if (!is.numeric(var)) - stop("Input values are not always numbers") - - # Build: brks, cols - colorbar <- ColorBar(brks = brks, cols = cols, vertical = FALSE, - plot = FALSE, ...) - brks <- colorbar$brks - cols <- colorbar$cols - - n.cols <- length(cols) ## number of colours - n.brks <- length(brks) ## number of intervals - - if (n.brks != n.cols + 1) - stop("There must be one break more than the number of colors") - ncols <- ncol(var) ## number of columns of the image - nrows <- nrow(var) ## number of rows of the image - if (ncols < 2) - stop("Matrix must have at least two columns") - if (nrows < 2) - stop("Matrix must have at least two rows") - if (!is.null(xlabels) && length(xlabels) != ncols) - stop(paste0("The number of x labels must be equal to the number of ", - "columns of the data matrix")) - if (!is.null(ylabels) && length(ylabels) != nrows) - stop(paste0("The number of y labels must be equal to the number of ", - "rows of the data matrix")) - if (!is.numeric(figure.width) || figure.width < 0) - stop("figure.width must be a positive number") - if (!is.numeric(legend.width) || legend.width < 0 || legend.width > 0.5) - stop("legend.width must be a number from 0 to 0.5") - - - # If there is any filenames to store the graphics, process them - # to select the right device - if (!is.null(fileout)) { - deviceInfo <- .SelectDevice(fileout = fileout, - width = 80 * ncols * figure.width, - height = 80 * nrows, - units = size_units, res = res) - saveToFile <- deviceInfo$fun - fileout <- deviceInfo$files - } - - # Open connection to graphical device - if (!is.null(fileout)) { - saveToFile(fileout) - } else if (names(dev.cur()) == 'null device') { - dev.new(units = size_units, res = res, - width = 8 * figure.width, height = 5) - } - - if (!is.null(fileout)) { - - # Draw empty plot: - par(mar = c(4, 4, 1, 0), fig = c(0.1, 1 - legend.width, 0.1, 0.9)) - plot(1, 1, type = "n", xaxt = "n", yaxt = "n", ylim = c(0.5, nrows + 0.5), - xlim = c(-0.5, ncols - 1 + 0.5), ann = F, bty = "n") - - # Add axes titles: - label.size <- 1.2 * (max(ncols, nrows) / 10) ^ 0.5 - mtext(side = 1, text = xtitle, line = line, cex = label.size, font = 3) - mtext(side = 2, text = ytitle, line = 3, cex = label.size, font = 3) - - # Add plot title: - if (is.null(title.color)) title.color <- "royalblue4" - mtext(side = 3, text = toptitle, cex = 1.75 * (nrows / 10) ^ 0.7, - col = title.color) - - # Add axis labels: - axis.size <- (max(ncols, nrows) / 10) ^ 0.3 - if (is.null(xlabels)) xlabels = 1:ncols - if (is.null(ylabels)) ylabels = 1:nrows - axis(1, at = seq(0, ncols - 1), las = ifelse(xvert, 2, 1), labels = xlabels, - cex.axis = axis.size, tck = 0, lwd = 0, line = - 1 - (nrows / 10 - 1)) ## Add x-axis labels - axis(2, at = seq(1, nrows), las = 1, labels = rev(ylabels), - cex.axis = axis.size, tck = 0, lwd = 0, line = 0.5 - ncols / 10) ## Add y-axis labels - - } else { - - # Draw empty plot: - par(mar = c(4, 4, 1, 0), fig = c(0.1, 1 - legend.width, 0.1, 0.9)) - plot(1, 1, type = "n", xaxt = "n", yaxt = "n", ylim = c(0.5, nrows + 0.5), - xlim = c(-0.5, ncols - 1 + 0.5), ann = F, bty = "n") - - # Add axes titles: - label.size <- 1.2 # * (max(ncols, nrows) / 10) ^ 0.5 - mtext(side = 1, text = xtitle, line = line, cex = label.size, font = 3) - mtext(side = 2, text = ytitle, line = 3, cex = label.size, font = 3) - - # Add plot title: - if (is.null(title.color)) title.color <- "royalblue4" - mtext(side = 3, text = toptitle, cex = 1.5, #* (nrows / 10) ^ 0.7, - col = title.color) - - # Add axis labels: - axis.size <- 1 #(max(ncols, nrows) / 10) ^ 0.3 - if (is.null(xlabels)) xlabels = 1:ncols - if (is.null(ylabels)) ylabels = 1:nrows - axis(1, at = seq(0, ncols - 1), las = ifelse(xvert, 2, 1), labels = xlabels, - cex.axis = axis.size, tck = 0, lwd = 0, line = - 1 - (nrows / 10 - 1)) ## Add x-axis labels - axis(2, at = seq(1, nrows), las = 1, labels = rev(ylabels), - cex.axis = axis.size, tck = 0, lwd = 0, line = 0.5 - ncols / 10) ## Add y-axis labels - - } - - # Create an array of colors instead of numbers (it starts all gray): - array.colors <- array("gray", c(nrows, ncols)) - for (int in n.cols:1) array.colors[var <= brks[int + 1]] <- cols[int] - - # fill with colors the cells in the figure: - for (p in 1:nrows) { - for (l in 0:(ncols - 1)) { - polygon(c(0.5 + l - 1, 0.5 + l - 1, 1.5 + l - 1, 1.5 + l - 1), - c(-0.5 + nrows + 1 - p, 0.5 + nrows + 1 - p, - 0.5 + nrows + 1 - p, -0.5 + nrows + 1 - p), - col = array.colors[p, 1 + l], border = "black") - } - } - - # Draw color legend: - if (legend) { - par(fig = c(1 - legend.width - 0.01, - 1 - legend.width + legend.width * min(1, 10 / ncols), - 0.3, 0.8), new = TRUE) - #legend.label.size <- (max(ncols, nrows) / 10) ^ 0.4 - ColorBar(brks = brks, cols = cols, vertical = TRUE, ...) - } - - # If the graphic was saved to file, close the connection with the device - if (!is.null(fileout)) dev.off() - invisible(list(brks = brks, cols = cols)) - -} diff --git a/R/Trend.R b/R/Trend.R index 56819bb7..15ec7ebe 100644 --- a/R/Trend.R +++ b/R/Trend.R @@ -1,41 +1,37 @@ #'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. The trend would be -#'provided in number of units per month or year. This function also returns the -#'time series of the detrended ensemble mean forecasts. The confidence interval -#'relies on a student-T distribution.\cr -#'.Trend() provides the same functionality but taking a matrix ensemble members +#'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 An array of any number of dimensions up to 10. -#'@param exp An M by N matrix representing M forecasts from N ensemble members. -#'@param interval A number of months/years between 2 points along posTR -#' dimension. Set 1 as default. -#'@param siglev A numeric value indicating the confidence level for the -#' computation of confidence interval. Set 0.95 as default. -#'@param conf A logical value indicating whether to compute the confidence -#' levels or not. Set TRUE as default. -#'@param posTR An integer indicating the position along which to compute the -#' trend. +#'@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}{ -#' An array with same dimensions as parameter 'var' except along the posTR -#' dimension, which is replaced by a length 4 (or length 2 if conf = FALSE) -#' dimension, corresponding to the lower limit of the confidence interval -#' (only present if conf = TRUE), the slope, the upper limit of the confidence -#' interval (only present if conf = TRUE), and the intercept. +#' The intercept and slope coefficients for the least squares fitting of the +#' trend. #'} -#'\item{$detrended}{ -#' Same dimensions as var with linearly detrended var along the posTR -#' dimension. -#'} -#'Only in .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 diff --git a/man/PlotMatrix.Rd b/man/PlotMatrix.Rd deleted file mode 100644 index 18d15c11..00000000 --- a/man/PlotMatrix.Rd +++ /dev/null @@ -1,89 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/PlotMatrix.R -\name{PlotMatrix} -\alias{PlotMatrix} -\title{Function to convert any numerical table to a grid of coloured squares.} -\usage{ -PlotMatrix(var, brks = NULL, cols = NULL, toptitle = NULL, - title.color = "royalblue4", xtitle = NULL, ytitle = NULL, - xlabels = NULL, xvert = FALSE, ylabels = NULL, line = 3, - figure.width = 1, legend = TRUE, legend.width = 0.15, fileout = NULL, - size_units = "px", res = 100, ...) -} -\arguments{ -\item{var}{A numerical matrix containing the values to be displayed in a -colored image.} - -\item{brks}{A vector of the color bar intervals. The length must be one more -than the parameter 'cols'. Use ColorBar() to generate default values.} - -\item{cols}{A vector of valid color identifiers for color bar. The length -must be one less than the parameter 'brks'. Use ColorBar() to generate -default values.} - -\item{toptitle}{A string of the title of the grid. Set NULL as default.} - -\item{title.color}{A string of valid color identifier to decide the title -color. Set "royalblue4" as default.} - -\item{xtitle}{A string of title of the x-axis. Set NULL as default.} - -\item{ytitle}{A string of title of the y-axis. Set NULL as default.} - -\item{xlabels}{A vector of labels of the x-axis. The length must be -length of the column of parameter 'var'. Set the sequence from 1 to the -length of the column of parameter 'var' as default.} - -\item{xvert}{A logical value to decide whether to place x-axis labels -vertically. Set FALSE as default, which keeps the labels horizontally.} - -\item{ylabels}{A vector of labels of the y-axis The length must be -length of the row of parameter 'var'. Set the sequence from 1 to the -length of the row of parameter 'var' as default.} - -\item{line}{An integer specifying the distance between the title of the -x-axis and the x-axis. Set 3 as default. Adjust if the x-axis labels -are long.} - -\item{figure.width}{A positive number as a ratio adjusting the width of the -grids. Set 1 as default.} - -\item{legend}{A logical value to decide to draw the grid color legend or not. -Set TRUE as default.} - -\item{legend.width}{A number between 0 and 0.5 to adjust the legend width. -Set 0.15 as default.} - -\item{fileout}{A string of full directory path and file name indicating where -to save the plot. If not specified (default), a graphics device will pop up.} - -\item{size_units}{A string indicating the units of the size of the device -(file or window) to plot in. Set 'px' as default. See ?Devices and the -creator function of the corresponding device.} - -\item{res}{A positive number indicating resolution of the device (file or window) -to plot in. See ?Devices and the creator function of the corresponding device.} - -\item{...}{The additional parameters to be passed to function ColorBar() in -s2dverification for color legend creation.} -} -\value{ -A figure in popup window by default, or saved to the specified path. -} -\description{ -This function converts a numerical data matrix into a coloured -grid. It is useful for a slide or article to present tabular results as -colors instead of numbers. -} -\examples{ -#Example with random data -PlotMatrix(var = matrix(rnorm(n = 120, mean = 0.3), 10, 12), - cols = c('white','#fef0d9','#fdd49e','#fdbb84','#fc8d59', - '#e34a33','#b30000', '#7f0000'), - brks = c(-1, 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 1), - toptitle = "Mean Absolute Error", - xtitle = "Forecast time (month)", ytitle = "Start date", - xlabels = c("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", - "Aug", "Sep", "Oct", "Nov", "Dec")) -} - diff --git a/man/Trend.Rd b/man/Trend.Rd index e7035e3d..da1fe956 100644 --- a/man/Trend.Rd +++ b/man/Trend.Rd @@ -10,47 +10,43 @@ Trend(var, posTR = 2, interval = 1, siglev = 0.95, conf = TRUE) .Trend(exp, interval = 1, siglev = 0.95, conf = TRUE) } \arguments{ -\item{var}{An array of any number of dimensions up to 10.} +\item{var}{Array of any number of dimensions up to 10.} -\item{posTR}{An integer indicating the position along which to compute the -trend.} +\item{posTR}{Position along which to compute the trend.} -\item{interval}{A number of months/years between 2 points along posTR -dimension. Set 1 as default.} +\item{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.} -\item{siglev}{A numeric value indicating the confidence level for the -computation of confidence interval. Set 0.95 as default.} +\item{siglev}{Confidence level for the computation of confidence interval. +0.95 by default.} -\item{conf}{A logical value indicating whether to compute the confidence -levels or not. Set TRUE as default.} +\item{conf}{Whether to compute the confidence levels or not. TRUE by default.} -\item{exp}{An M by N matrix representing M forecasts from N ensemble members.} +\item{exp}{M by N matrix of M forecasts from N ensemble members.} } \value{ \item{$trend}{ - An array with same dimensions as parameter 'var' except along the posTR - dimension, which is replaced by a length 4 (or length 2 if conf = FALSE) - dimension, corresponding to the lower limit of the confidence interval - (only present if conf = TRUE), the slope, the upper limit of the confidence - interval (only present if conf = TRUE), and the intercept. + The intercept and slope coefficients for the least squares fitting of the + trend. } -\item{$detrended}{ - Same dimensions as var with linearly detrended var along the posTR - dimension. -} -Only in .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. } } \description{ Computes the trend along the forecast time of the ensemble mean by least -square fitting, and the associated error interval. The trend would be -provided in number of units per month or year. This function also returns the -time series of the detrended ensemble mean forecasts. The confidence interval -relies on a student-T distribution.\cr -.Trend() provides the same functionality but taking a matrix ensemble members +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). } \examples{ -- GitLab