From 7ab6f5f5ab21f4fb00e924d339d7b4cc6b11713e Mon Sep 17 00:00:00 2001 From: ncortesi Date: Fri, 1 Feb 2019 16:37:54 +0100 Subject: [PATCH 1/3] Added PlotMatrix.R --- R/PlotMatrix.R | 115 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 R/PlotMatrix.R diff --git a/R/PlotMatrix.R b/R/PlotMatrix.R new file mode 100644 index 00000000..3fb79bae --- /dev/null +++ b/R/PlotMatrix.R @@ -0,0 +1,115 @@ +#'Function to convert any numerical table to a grid of coloured squares. +#' +#'@description This function converts a numerical data matrix in a coloured grid. Useful in a slide or article, to present tabular results as colors instead of numbers. +#' +#'@param table numerical matrix containing the values to be displayed in a colored image. +#'@param colors A vector with the color sequence to use in the grid. +#'@param brks A vector with the intervals to split the data into. There must be one \code{brks} more than the number of \code{colors}. +#'@param title The title of the grid. Default is NULL (no title). +#'@param title.color Color to use for the title (default is dark blue). +#'@param xtitle Title of the x-axis (default is NULL) +#'@param ytitle Title of the y-axis (default is NULL) +#'@param xlabels Vector of length ncol(\code{table}) with the labels of the x-axis (default is a sequence from 1 to the number of columns). +#'@param xvert If x-axis labels are too long, it is possible to place them vertically by setting \code{xvert} to TRUE (default is FALSE). +#'@param ylabels Vector of length nrow(\code{table}) with the labels of the y-axis (default is a sequence from 1 to the number of rows). +#'@param line Distance of the title of the x-axis from the x-axis (default is 3 lines). Adjust as necessary if your x-axis labels are long. +#'@param figure.width If the form of the grid cells is not perfectly squared, it is possible adjust it by multiplying the grid width for this factor (default is 1). +#'@param legend Set it to FALSE not to draw the grid color legend (default is TRUE). +#'@param legend.width If the width of the color legend is too small or too large, it can be adjusted by increasing or decreasing the legend width (default is 0.15) +#'@param file Set the path and the filename where the .png image of the grid will be saved (default is 'PlotMatrix.png' in the working directory). +#'@param ... Set additional parameters to pass to draw the color legend with function ColorBar() of package s2dverification. +#' +#'@return No data is returned. Only the grid image is saved in a .png file specified by the user. +#' +#'@examples +#'#Example with random data (by default it is saved in the working directory, but the user can specify a different one): +#' +#' PlotMatrix(table = matrix(rnorm(n = 120, mean = 0.3), 10, 12), +#' colors = 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), +#' title = "Mean Absolute Error", xtitle = "Forecast time (month)", ytitle = "Start date", +#' xlabels = c("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")) +#' +#'@export + +PlotMatrix <- function(table, colors, brks, title = 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, file = NULL, ...){ + + # Check variables: + if (!is.matrix(table)) + stop("Input values are not a matrix") + if (!is.numeric(table)) + stop("Input values are not always numbers") + if (is.null(colors) || length(colors) < 2) + stop("You have to specify a color palette of at least 2 colors") + if (is.null(brks) || length(brks) < 2) + stop("You have to specify 2 or more intervals") + n.colors <- length(colors) ## number of colours + n.brks <- length(brks) ## number of intervals + if (n.brks != n.colors + 1) + stop("There must be one break more than the number of colors") + n.cols <- ncol(table) ## number of columns of the image + n.rows <- nrow(table) ## number of rows of the image + if (n.cols < 2) + stop("Matrix must have at least two columns") + if (n.rows < 2) + stop("Matrix must have at least two rows") + if (!is.null(xlabels) && length(xlabels) != n.cols) + stop("The number of x labels must be equal to the number of columns of the data matrix") + if (!is.null(ylabels) && length(ylabels) != n.rows) + stop("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") + + # Print output file: + if (is.null(file)) file.output <- paste0(getwd(), "/PlotMatrix.png") else file.output <- file + print(paste0("Saving grid image in: ", file.output)) + + # Generate image: + png(file = file.output, width = 55 * n.cols * figure.width, height = 50 * n.rows) + plot.new() + + # Draw empty plot: + par(mar = c(4, 4, 1, 0), fig = c(0.1, 1 - legend.width, 0.1, 0.9), new = TRUE) + plot(1, 1, type = "n", xaxt = "n", yaxt = "n", ylim = c(0.5, n.rows + 0.5), xlim = c(-0.5, n.cols - 1 + 0.5), ann = F, bty = "n") + + # Add axes titles: + label.size <- 1.2 * (max(n.cols, n.rows) / 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 = title, cex = 1.75 * (n.rows / 10) ^ 0.7, col = title.color) + + # Add axis labels: + axis.size <- (max(n.cols, n.rows) / 10) ^ 0.3 + if (is.null(xlabels)) xlabels = 1:n.cols + if (is.null(ylabels)) ylabels = 1:n.rows + axis(1, at = seq(0, n.cols-1), las = ifelse(xvert, 2, 1), labels = xlabels, cex.axis = axis.size, tck = 0, lwd = 0, line = - 1 - (n.rows / 10 - 1)) ## Add x-axis labels + axis(2, at = seq(1, n.rows), las = 1, labels = rev(ylabels), cex.axis = axis.size, tck = 0, lwd = 0, line = 0.5 - n.cols / 10) ## Add y-axis labels + + # Create an array of colors instead of numbers (it starts all gray): + array.colors <- array("gray", c(n.rows, n.cols)) + for (int in n.colors:1) array.colors[table <= brks[int + 1]] <- colors[int] + + # fill with colors the cells in the figure: + for (p in 1:n.rows){ + for (l in 0:(n.cols - 1)){ + polygon(c(0.5 + l - 1, 0.5 + l - 1, 1.5 + l - 1, 1.5 + l - 1), + c(-0.5 + n.rows + 1 - p, 0.5 + n.rows + 1 - p, 0.5 + n.rows + 1 - p, -0.5 + n.rows + 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 / n.cols), 0.3, 0.8), new=TRUE) + legend.label.size <- (max(n.cols, n.rows) / 10) ^ 0.4 + ColorBar(brks, cols = colors, vert = TRUE, label_scale = legend.label.size, subsample = 1, ...) + } + + dev.off() +} + -- GitLab From ffe52eaf4f6989c952050f2d8e8280e0e3caed1b Mon Sep 17 00:00:00 2001 From: aho Date: Tue, 3 Sep 2019 12:17:30 +0200 Subject: [PATCH 2/3] Modify PlotMatrix(). Update branch to master. --- NAMESPACE | 1 + R/PlotMatrix.R | 238 +++++++++++++++++++++++++++++++--------------- man/PlotMatrix.Rd | 89 +++++++++++++++++ 3 files changed, 252 insertions(+), 76 deletions(-) create mode 100644 man/PlotMatrix.Rd diff --git a/NAMESPACE b/NAMESPACE index 3e35710e..4e855789 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -56,6 +56,7 @@ 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 index 3fb79bae..32a40c99 100644 --- a/R/PlotMatrix.R +++ b/R/PlotMatrix.R @@ -1,115 +1,201 @@ #'Function to convert any numerical table to a grid of coloured squares. #' -#'@description This function converts a numerical data matrix in a coloured grid. Useful in a slide or article, to present tabular results as colors instead of numbers. +#'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 table numerical matrix containing the values to be displayed in a colored image. -#'@param colors A vector with the color sequence to use in the grid. -#'@param brks A vector with the intervals to split the data into. There must be one \code{brks} more than the number of \code{colors}. -#'@param title The title of the grid. Default is NULL (no title). -#'@param title.color Color to use for the title (default is dark blue). -#'@param xtitle Title of the x-axis (default is NULL) -#'@param ytitle Title of the y-axis (default is NULL) -#'@param xlabels Vector of length ncol(\code{table}) with the labels of the x-axis (default is a sequence from 1 to the number of columns). -#'@param xvert If x-axis labels are too long, it is possible to place them vertically by setting \code{xvert} to TRUE (default is FALSE). -#'@param ylabels Vector of length nrow(\code{table}) with the labels of the y-axis (default is a sequence from 1 to the number of rows). -#'@param line Distance of the title of the x-axis from the x-axis (default is 3 lines). Adjust as necessary if your x-axis labels are long. -#'@param figure.width If the form of the grid cells is not perfectly squared, it is possible adjust it by multiplying the grid width for this factor (default is 1). -#'@param legend Set it to FALSE not to draw the grid color legend (default is TRUE). -#'@param legend.width If the width of the color legend is too small or too large, it can be adjusted by increasing or decreasing the legend width (default is 0.15) -#'@param file Set the path and the filename where the .png image of the grid will be saved (default is 'PlotMatrix.png' in the working directory). -#'@param ... Set additional parameters to pass to draw the color legend with function ColorBar() of package s2dverification. -#' -#'@return No data is returned. Only the grid image is saved in a .png file specified by the user. +#'@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 (by default it is saved in the working directory, but the user can specify a different one): -#' -#' PlotMatrix(table = matrix(rnorm(n = 120, mean = 0.3), 10, 12), -#' colors = 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), -#' title = "Mean Absolute Error", xtitle = "Forecast time (month)", ytitle = "Start date", -#' xlabels = c("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")) -#' +#'#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(table, colors, brks, title = 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, file = NULL, ...){ +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(table)) + if (!is.matrix(var)) stop("Input values are not a matrix") - if (!is.numeric(table)) + if (!is.numeric(var)) stop("Input values are not always numbers") - if (is.null(colors) || length(colors) < 2) - stop("You have to specify a color palette of at least 2 colors") - if (is.null(brks) || length(brks) < 2) - stop("You have to specify 2 or more intervals") - n.colors <- length(colors) ## number of colours + + # 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.colors + 1) + + if (n.brks != n.cols + 1) stop("There must be one break more than the number of colors") - n.cols <- ncol(table) ## number of columns of the image - n.rows <- nrow(table) ## number of rows of the image - if (n.cols < 2) + 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 (n.rows < 2) + if (nrows < 2) stop("Matrix must have at least two rows") - if (!is.null(xlabels) && length(xlabels) != n.cols) - stop("The number of x labels must be equal to the number of columns of the data matrix") - if (!is.null(ylabels) && length(ylabels) != n.rows) - stop("The number of y labels must be equal to the number of rows of the data matrix") + 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") - - # Print output file: - if (is.null(file)) file.output <- paste0(getwd(), "/PlotMatrix.png") else file.output <- file - print(paste0("Saving grid image in: ", file.output)) - # Generate image: - png(file = file.output, width = 55 * n.cols * figure.width, height = 50 * n.rows) - plot.new() + # 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), new = TRUE) - plot(1, 1, type = "n", xaxt = "n", yaxt = "n", ylim = c(0.5, n.rows + 0.5), xlim = c(-0.5, n.cols - 1 + 0.5), ann = F, bty = "n") + 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(n.cols, n.rows) / 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) + 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 = title, cex = 1.75 * (n.rows / 10) ^ 0.7, col = title.color) + 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(n.cols, n.rows) / 10) ^ 0.3 - if (is.null(xlabels)) xlabels = 1:n.cols - if (is.null(ylabels)) ylabels = 1:n.rows - axis(1, at = seq(0, n.cols-1), las = ifelse(xvert, 2, 1), labels = xlabels, cex.axis = axis.size, tck = 0, lwd = 0, line = - 1 - (n.rows / 10 - 1)) ## Add x-axis labels - axis(2, at = seq(1, n.rows), las = 1, labels = rev(ylabels), cex.axis = axis.size, tck = 0, lwd = 0, line = 0.5 - n.cols / 10) ## Add y-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(n.rows, n.cols)) - for (int in n.colors:1) array.colors[table <= brks[int + 1]] <- colors[int] + 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:n.rows){ - for (l in 0:(n.cols - 1)){ + 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 + n.rows + 1 - p, 0.5 + n.rows + 1 - p, 0.5 + n.rows + 1 - p, -0.5 + n.rows + 1 - p), col = array.colors[p, 1 + l], border = "black") + 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 / n.cols), 0.3, 0.8), new=TRUE) - legend.label.size <- (max(n.cols, n.rows) / 10) ^ 0.4 - ColorBar(brks, cols = colors, vert = TRUE, label_scale = legend.label.size, subsample = 1, ...) + 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, ...) } - dev.off() + # 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/man/PlotMatrix.Rd b/man/PlotMatrix.Rd new file mode 100644 index 00000000..18d15c11 --- /dev/null +++ b/man/PlotMatrix.Rd @@ -0,0 +1,89 @@ +% 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")) +} + -- GitLab From 58a7ee8b7de334b6aa5d3a04a5804ae7800e7b2e Mon Sep 17 00:00:00 2001 From: aho Date: Tue, 3 Sep 2019 15:15:54 +0200 Subject: [PATCH 3/3] Correct bad documentation in Trend() --- R/Trend.R | 46 +++++++++++++++++++++++++--------------------- man/Trend.Rd | 46 +++++++++++++++++++++++++--------------------- 2 files changed, 50 insertions(+), 42 deletions(-) diff --git a/R/Trend.R b/R/Trend.R index 15ec7ebe..56819bb7 100644 --- a/R/Trend.R +++ b/R/Trend.R @@ -1,37 +1,41 @@ #'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 +#'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 #'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. +#'@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. #' #'@return #'\item{$trend}{ -#' The intercept and slope coefficients for the least squares fitting of the -#' 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. #'} -#'\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. #'} +#'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. +#'} #' #'@keywords datagen #'@author History:\cr diff --git a/man/Trend.Rd b/man/Trend.Rd index da1fe956..e7035e3d 100644 --- a/man/Trend.Rd +++ b/man/Trend.Rd @@ -10,43 +10,47 @@ Trend(var, posTR = 2, interval = 1, siglev = 0.95, conf = TRUE) .Trend(exp, interval = 1, siglev = 0.95, conf = TRUE) } \arguments{ -\item{var}{Array of any number of dimensions up to 10.} +\item{var}{An array of any number of dimensions up to 10.} -\item{posTR}{Position along which to compute the trend.} +\item{posTR}{An integer indicating the position along which to compute the +trend.} -\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{interval}{A number of months/years between 2 points along posTR +dimension. Set 1 as default.} -\item{siglev}{Confidence level for the computation of confidence interval. -0.95 by default.} +\item{siglev}{A numeric value indicating the confidence level for the +computation of confidence interval. Set 0.95 as default.} -\item{conf}{Whether to compute the confidence levels or not. TRUE by default.} +\item{conf}{A logical value indicating whether to compute the confidence +levels or not. Set TRUE as default.} -\item{exp}{M by N matrix of M forecasts from N ensemble members.} +\item{exp}{An M by N matrix representing M forecasts from N ensemble members.} } \value{ \item{$trend}{ - The intercept and slope coefficients for the least squares fitting of the - 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. } -\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. } +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. +} } \description{ 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 +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 as input (exp). } \examples{ -- GitLab