R/VizTriangles4Categories.R

In esviz: Plotting Functions for Climate Science and Services

#'Function to convert any 3-d numerical array to a grid of coloured triangles. 
#'
#'This function converts a 3-d numerical data array into a coloured 
#'grid with triangles. It is useful for a slide or article to present tabular 
#'results as colors instead of numbers. This can be used to compare the outputs 
#'of two or four categories (e.g. modes  of variability, clusters, or forecast 
#'systems). 
#'
#'@param data Array with three named dimensions: 'dimx', 'dimy', 'dimcat', 
#'  containing the values to be displayed in a coloured image with triangles.
#'@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 colour 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 sig_data Logical array with the same dimensions as 'data' to add layers 
#'  to the plot. A value of TRUE at a grid cell will draw a dot/symbol on the 
#'  corresponding triangle of the plot. Set NULL as default.
#'@param pch_sig Symbol to be used to represent sig_data. Takes 18 
#' (diamond) by default. See 'pch' in par() for additional accepted options.
#'@param col_sig Colour of the symbol to represent sig_data. 
#'@param cex_sig Parameter to increase/reduce the size of the symbols used 
#'  to represent sig_data.
#'@param xlab A logical value (TRUE) indicating if xlabels should be plotted
#'@param ylab A logical value (TRUE) indicating if ylabels should be plotted
#'@param xlabels A vector of labels of the x-axis The length must be 
#'  length of the col of parameter 'data'. Set the sequence from 1 to the 
#'  length of the row of parameter 'data' as default.
#'@param xtitle A string of title of the x-axis. Set NULL as default.
#'@param ylabels A vector of labels of the y-axis The length must be 
#'  length of the row of parameter 'data'. Set the sequence from 1 to the 
#'  length of the row of parameter 'data' as default. 
#'@param ytitle A string of title of the y-axis. Set NULL as default.
#'@param drawleg A logical value to decide to draw the color bar legend or not. 
#'  Set TRUE as default.
#'@param legend Deprecated. Use 'drawleg' instead.
#'@param lab_legend A vector of labels indicating what is represented in each 
#'category (i.e. triangle). Set the sequence from 1 to the length of 
#' the categories (2 or 4).  
#'@param cex_leg A number to indicate the increase/reductuion of the lab_legend  
#'  used to represent sig_data.
#'@param col_leg Color of the legend (triangles).
#'@param cex_axis A number to indicate the increase/reduction of the axis labels.
#'@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 mar A numerical vector of the form c(bottom, left, top, right) which 
#'  gives the number of lines of margin to be specified on the four sides of the 
#'  plot. 
#'@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 figure.width a numeric value to control the width of the plot.
#'@param ... The additional parameters to be passed to function 
#'  ColorBarContinuous() in for color legend creation.
#'@return A figure in popup window by default, or saved to the specified path.
#'
#'@author History:\cr
#'1.0  -  2020-10  (V.Torralba, \email{veronica.torralba@bsc.es})  -  Original code
#'
#'@examples 
#'# Example with random data
#'arr1 <- array(runif(n = 4 * 5 * 4, min = -1, max = 1), dim = c(4,5,4))
#'names(dim(arr1)) <- c('dimx', 'dimy', 'dimcat')
#'arr2 <- array(TRUE, dim = dim(arr1))
#'arr2[which(arr1 < 0.3)] <- FALSE
#'VizTriangles4Categories(data = arr1,
#'                        cols = c('white','#fef0d9','#fdd49e','#fdbb84','#fc8d59'),
#'                        brks = c(-1, 0, 0.1, 0.2, 0.3, 0.4), 
#'                        lab_legend = c('NAO+', 'BL','AR','NAO-'), 
#'                        xtitle = "Target month", ytitle = "Lead time",
#'                        xlabels = c("Jan", "Feb", "Mar", "Apr"))
#'
#'@importFrom grDevices dev.new dev.off dev.cur 
#'@importFrom graphics plot points polygon text title axis
#'@importFrom RColorBrewer brewer.pal
#'@importFrom ClimProjDiags Subset
#'@export
VizTriangles4Categories <- function(data, brks = NULL, cols = NULL,
                                    toptitle = NULL, sig_data = NULL,
                                    pch_sig = 18, col_sig = 'black',
                                    cex_sig = 1, xlab = TRUE, ylab = TRUE,
                                    xlabels = NULL, xtitle = NULL, 
                                    ylabels = NULL, ytitle = NULL,
                                    drawleg = TRUE, legend = NULL,
                                    lab_legend = NULL, cex_leg = 1,
                                    col_leg = 'black', cex_axis = 1.5,
                                    mar = c(5, 4, 0, 0), fileout = NULL,
                                    size_units = 'px', res = 100,
                                    figure.width = 1, ...) {
  # Checking the dimensions
  if (length(dim(data)) != 3) {
    stop("Parameter 'data' must be an array with three dimensions.")
  }
  
  if (any(is.na(data))){
    stop("Parameter 'data' cannot contain NAs.")
  }
  
  if (is.null(names(dim(data)))) {
    stop("Parameter 'data' must be an array with named dimensions.")
  }else{
    if (!any(names(dim(data)) == 'dimx') | !any(names(dim(data)) == 'dimy') |
        !any(names(dim(data)) == 'dimcat')) {
      stop("Parameter 'data' should contain 'dimx', 'dimy' and 'dimcat' dimension names. ")
    }
  }
  if (!is.vector(mar) & length(mar) != 4) {
    stop("Parameter 'mar' must be a vector of length 4.")
  }
  if (!is.null(sig_data)) {
    if (!is.logical(sig_data)) {
      stop("Parameter 'sig_data' array must be logical.")}
    else if (length(dim(sig_data)) != 3) {
      stop("Parameter 'sig_data' must be an array with three dimensions.")
    }else if (any(dim(sig_data) != dim(data))){
      stop("Parameter 'sig_data' must be an array with the same dimensions as 'data'.") 
    }else if(!is.null(names(dim(sig_data)))) {
      if (any(names(dim(sig_data)) != names(dim(data)))) {
        stop("Parameter 'sig_data' must be an array with the same named dimensions as 'data'.")}
    }
  }

  if (dim(data)['dimcat'] != 4 && dim(data)['dimcat'] != 2) {
    stop(
      "Parameter 'data' should contain a dimcat dimension with length equals
      to two or four as only two or four categories can be plotted.")
  }
  
  # Check drawleg
  if (missing(drawleg) && !missing(legend)) {
    warning("The parameter 'legend' is deprecated. Use 'drawleg' instead.")
    drawleg <- legend
  }
  if (!is.logical(drawleg) || length(drawleg) != 1) {
    stop("Parameter 'drawleg' must be a single logical value.")
  }
  
  # Checking what is available and generating missing information 
  if (!is.null(lab_legend) &&
      length(lab_legend) != 4 && length(lab_legend) != 2) {
    stop("Parameter 'lab_legend' should contain two or four names.")
  }
  
  datadim <- dim(data)
  nrow <- dim(data)['dimy']
  ncol <- dim(data)['dimx']
  ncat <- dim(data)['dimcat']
  
  # 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 * ncol * figure.width, 
                                height = 80 * nrow,
                                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)
  }
  oldpar <- par(no.readonly = TRUE)
  on.exit(par(oldpar), add = TRUE)
  
  if (is.null(xlabels)){
    xlabels = 1:ncol
  }
  if (is.null(ylabels)){
    ylabels = 1:nrow
  }

  if (!is.null(brks) && !is.null(cols)) {
    if (length(brks) != length(cols) + 1) {
      stop("The length of the parameter 'brks' must be one more than 'cols'.")
    }
  }  
  if (is.null(brks)) {
    brks <- seq(min(data, na.rm = T), max(data, na.rm = T), length.out = 9)
  }
  if (is.null(cols)) {
    cols <- rev(brewer.pal(length(brks) - 1, 'RdBu'))
  }
  
  # The colours for each triangle/category are defined
  data_cat <- array(cols[length(cols)], dim = datadim)
  names(dim(data_cat)) <- names(dim(data))
  for (i in (length(cols) - 1):1) {
    data_cat[data < brks[i + 1]] <- cols[i]
  }
  
  if(drawleg){
    layout(matrix(c(1, 2, 1, 3), 2, 2, byrow = T),
           widths = c(10, 3.4), heights = c(10, 3.5))
    par(oma = c(1, 1, 1, 1), mar = mar)
    if(is.null(lab_legend)) {
      lab_legend = 1:ncat
    }
  }
  
  plot(ncol, nrow, xlim = c(0, ncol), ylim=c(0, nrow), xaxs = "i", yaxs = 'i', type = "n", 
       xaxt = "n", yaxt = "n", ann = F, axes = F)
  
  box(col = 'black',lwd = 1)
  
  if (! is.null(toptitle)){
    title(toptitle, cex = 1.5)
  }
  
  if (!is.null(xtitle)){
    mtext(side = 1, text = xtitle, line = 4, cex = 1.5)
  }
  if (!is.null(ytitle)){
    mtext(side = 2, text = ytitle, line = 2.5, cex = 1.5)
  }
  
  if (xlab){
    axis(1, at =(1:ncol) - 0.5, las = 2, labels = xlabels, cex.axis = cex_axis)
  }
  if (ylab){
    axis(2, at = (1:nrow) - 0.5, las = 2, labels = ylabels, cex.axis = cex_axis)
  }
  
  
  #The triangles are plotted
  for(p in 1:ncol){
    for(l in 1:nrow){
      if (ncat == 4){
        coord_triangl <- list(xs=list(c(p-1, p-0.5, p-1),c(p-1, p-0.5, p),c(p, p-0.5, p),c(p-1, p-0.5, p)),
                              ys=list( c(l-1, -0.5+l, l), c(l-1, -0.5+l, l-1),c(l-1, -0.5+l, l),c(l, -0.5+l, l)))
        
        coord_sig <- list(x=c(p-0.75,p-0.5,p-0.25,p-0.5),y=c(l-0.5,l-0.75,l-0.5,l-0.25))
      }
      
      if (ncat==2){
        coord_triangl <- list(xs=list(c(p-1, p, p-1),c(p-1, p, p)),
                             ys=list(c(l-1, l, l),c(l-1,l-1, l)))
        coord_sig <- list(x=c(p-(2/3),p-(1/3)),y=c(l-(1/3),l-(2/3)))
      }
      for (n in 1:ncat) {
        polygon(coord_triangl$xs[[n]],
                coord_triangl$ys[[n]],
                col = Subset(
                  data_cat,
                  along = c('dimcat', 'dimx', 'dimy'),
                  indices = list(n, p, l)))
        if (!is.null(sig_data) &&
            Subset(sig_data,along = c('dimcat', 'dimx', 'dimy'),
                   indices = list(n, p, l))) {
          points(
            x = coord_sig$x[n],
            y = coord_sig$y[n],
            pch = pch_sig,
            cex = cex_sig,
            col = col_sig
          )
        }
      }
    }
  }
  
  # legend
  
  if(drawleg){
    # Colorbar
    par(mar=c(0,0,0,0))
    ColorBarContinuous(brks = brks, cols = cols, vertical = TRUE, 
                       draw_bar_ticks = TRUE, draw_separators = TRUE,
    #                  bar_extra_margin = c(0, 0, 2.5, 0)
                       bar_extra_margin = c( 0, 0, 0, 0), bar_label_scale = 1.5, ...)
    
    par(mar = c(0.5, 2.5, 0.5, 2.5))
    plot(1, 1, xlim = c(0, 1), ylim =c(0, 1), xaxs = "i", yaxs = 'i', type = "n", 
         xaxt = "n", yaxt = "n", ann = F, axes = F)
    
    box(col = col_leg)
    p = l = 1
    if (ncat == 4){
      coord_triangl <- list(xs = list(c(p -1, p - 0.5, p - 1), c(p - 1, p - 0.5, p),
                                      c(p, p - 0.5, p), c(p - 1, p - 0.5, p)),
                            ys = list(c(l - 1, - 0.5 + l, l), c(l - 1, - 0.5 + l, l - 1),
                                      c(l - 1, - 0.5 + l, l), c(l, - 0.5 + l, l)))
      
      coord_sig <- list(x = c(p - 0.75, p - 0.5, p - 0.25, p - 0.5), 
                        y = c(l - 0.5, l - 0.75, l - 0.5, l - 0.25))
    }
    
    if (ncat==2){
      coord_triangl<- list(xs=list(c(p-1, p, p),c(p-1, p, p-1)),
                           ys=list( c(l-1,l-1, l), c(l-1, l, l)))
      coord_sig<- list(x=c(p-(2/3),p-(1/3)),y=c(l-(1/3),l-(2/3)))
    }
    for (n in 1:ncat) {
      polygon(coord_triangl$xs[[n]],
              coord_triangl$ys[[n]],border=col_leg)
      text(x=coord_sig$x[[n]],y=coord_sig$y[[n]],labels = lab_legend[n],cex=cex_leg,col=col_leg)
      
    }
  }
  
  # If the graphic was saved to file, close the connection with the device
  if (!is.null(fileout)) dev.off()
}