plot_corr {COINr}R Documentation

Static heatmaps of correlation matrices


Generates heatmaps of correlation matrices using ggplot2, which can be tailored according to the grouping and structure of the index. This enables correlating any set of indicators against any other, and supports calling named aggregation groups of indicators. The withparent argument generates tables of correlations only with parents of each indicator. Also supports discrete colour maps using flagcolours, different types of correlation, and groups plots by higher aggregation levels.


  iCodes = NULL,
  Levels = 1,
  cortype = "pearson",
  withparent = FALSE,
  grouplev = NULL,
  box_level = NULL,
  showvals = TRUE,
  flagcolours = FALSE,
  flagthresh = NULL,
  pval = 0.05,
  insig_colour = "#F0F0F0",
  text_colour = NULL,
  discrete_colours = NULL,
  box_colour = NULL,
  order_as = NULL,
  use_directions = FALSE



The coin object


The target data set.


An optional list of character vectors where the first entry specifies the indicator/aggregate codes to correlate against the second entry (also a specification of indicator/aggregate codes)


The aggregation levels to take the two groups of indicators from. See get_data() for details.


Optional further arguments to pass to get_data().


The type of correlation to calculate, either "pearson", "spearman", or "kendall" (see stats::cor()).


If aglev[1] != aglev[2], and equal TRUE will only plot correlations of each row with its parent. If "family", plots the lowest aggregation level in Levels against all its parent levels. If FALSE plots the full correlation matrix (default).


The aggregation level to group correlations by if aglev[1] == aglev[2]. By default, groups correlations into the aggregation level above. Set to 0 to disable grouping and plot the full matrix.


The aggregation level to draw boxes around if aglev[1] == aglev[2].


If TRUE, shows correlation values. If FALSE, no values shown.


If TRUE, uses discrete colour map with thresholds defined by flagthresh. If FALSE uses continuous colour map.


A 3-length vector of thresholds for highlighting correlations, if flagcolours = TRUE. flagthresh[1] is the negative threshold (default -0.4). Below this value, values will be flagged red. flagthresh[2] is the "weak" threshold (default 0.3). Values between flagthresh[1] and flagthresh[2] are coloured grey. flagthresh[3] is the "high" threshold (default 0.9). Anything between flagthresh[2] and flagthresh[3] is flagged "OK", and anything above flagthresh[3] is flagged "high".


The significance level for plotting correlations. Correlations with p < pval will be shown, otherwise they will be plotted as the colour specified by insig_colour. Set to 0 to disable this.


The colour to plot insignificant correlations. Defaults to a light grey.


The colour of the correlation value text (default white).


An optional 4-length character vector of colour codes or names to define the discrete colour map if flagcolours = TRUE (from high to low correlation categories). Defaults to a green/blue/grey/purple.


The line colour of grouping boxes, default black.


Optional list for ordering the plotting of variables. If specified, this must be a list of length 2, where each entry of the list is a character vector of the iCodes plotted on the x and y axes of the plot. The plot will then follow the order of these character vectors. Note this must be used with care because the grouplev and boxlev arguments will not follow the reordering. Hence this argument is probably best used for plots with no grouping, or for simply re-ordering within groups.


Logical: if TRUE the extracted data is adjusted using directions found inside the coin (i.e. the "Direction" column input in iMeta: any indicators with negative direction will have their values multiplied by -1 which will reverse the direction of correlation). This should only be set to TRUE if the data set has not yet been normalised. For example, this can be useful to set to TRUE to analyse correlations in the raw data, but would make no sense to analyse correlations in the normalised data because that already has the direction adjusted! So you would reverse direction twice. In other words, use this at your discretion.


This function calls get_corr().

Note that this function can only call correlations within the same data set (i.e. only one data set in .$Data).

This function uses ggplot2 to generate plots, so the plot can be further manipulated using ggplot2 commands. See vignette("visualisation") for more details on plotting.

This function replaces the now-defunct plotCorr() from COINr < v1.0.


A plot object generated with ggplot2, which can be edited further with ggplot2 commands.


# build example coin
coin <- build_example_coin(up_to = "Normalise", quietly = TRUE)

# plot correlations between indicators in Sust group, using Normalised dset
plot_corr(coin, dset = "Normalised", iCodes = list("Sust"),
          grouplev = 2, flagcolours = TRUE)

[Package COINr version 1.1.7 Index]