esviz (version 0.0.2)

VizTriangles4Categories: Function to convert any 3-d numerical array to a grid of coloured triangles.

Description

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).

Usage

VizTriangles4Categories(
  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,
  ...
)

Value

A figure in popup window by default, or saved to the specified path.

Arguments

data

Array with three named dimensions: 'dimx', 'dimy', 'dimcat', containing the values to be displayed in a coloured image with triangles.

brks

A vector of the color bar intervals. The length must be one more than the parameter 'cols'. Use ColorBar() to generate default values.

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.

toptitle

A string of the title of the grid. Set NULL as default.

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.

pch_sig

Symbol to be used to represent sig_data. Takes 18 (diamond) by default. See 'pch' in par() for additional accepted options.

col_sig

Colour of the symbol to represent sig_data.

cex_sig

Parameter to increase/reduce the size of the symbols used to represent sig_data.

xlab

A logical value (TRUE) indicating if xlabels should be plotted

ylab

A logical value (TRUE) indicating if ylabels should be plotted

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.

xtitle

A string of title of the x-axis. Set NULL as default.

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.

ytitle

A string of title of the y-axis. Set NULL as default.

drawleg

A logical value to decide to draw the color bar legend or not. Set TRUE as default.

legend

Deprecated. Use 'drawleg' instead.

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).

cex_leg

A number to indicate the increase/reductuion of the lab_legend used to represent sig_data.

col_leg

Color of the legend (triangles).

cex_axis

A number to indicate the increase/reduction of the axis labels.

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.

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.

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.

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.

figure.width

a numeric value to control the width of the plot.

...

The additional parameters to be passed to function ColorBarContinuous() in for color legend creation.

Author

History:
1.0 - 2020-10 (V.Torralba, ) - 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"))