ggcorrm: Create a ggcorrm correlation plot
In r-link/corrmorant: Flexible Correlation Matrices Based on 'ggplot2'

Description Usage Arguments Details Value See Also Examples

ggcorrm() initializes a ggcorrm object (inheriting from class ggplot). It can be called either using the raw data for the correlation plot as input, which is then internally passed to tidy_corrm(), or with a prepared correlation dataset of class tidy_corrm.

ggcorrm(
  data,
  mapping = NULL,
  labels = NULL,
  rescale = c("as_is", "by_sd", "by_range"),
  corr_method = c("pearson", "kendall", "spearman"),
  corr_group = NULL,
  mutates = NULL,
  bg_dia = NULL,
  bg_lotri = NULL,
  bg_utri = NULL,
  facet_arg = NULL
)

`data`	Dataset used to compute the correlation matrix. Can be either a `data.frame` or `matrix`, or an object of class `tidy_corrm`. If specifying a `data.frame` or `matrix`, it will internally be passed to `tidy_corrm()` with the settings for `labels`, `rescale`, `corr_group`, `corr_method` and `mutates` specified in the `ggcorrm()` call. `tidy_corrm()` prepares the data for plotting by creating a `data.frame` with all possible combinations of all numeric variables, while retaining all discrete variables in additional columns. If a `tidy_corrm` object is supplied, all arguments passed to `tidy_corrm()` will be ignored and the `tidy_corrm` object wil be used directly to initialize the `ggcorrm` plot.
`mapping`	Set of aesthetic mappings created by aes that are passed on to subsequent layers. `x` and `y` are set automatically and must not be changed, but all other aesthetics may be manipulated. Defaults to `NULL` (use standard `ggcorrm` mapping).
`labels`	(Optional) character vector or function. If a character, must contain labels for the names of all numeric columns that are used to replace the column names in the plot axis and text labels and must be of the same length as the number of numeric columns displayed in the plot. If a function, must take the original names of the numeric columns as an argument and return a character vector with the same length. Defaults to `NULL` (use original column names as labels).
`rescale`	character string specifying the type of transformation performed on the numeric variables in the plot. The standard argument `as_is"` uses the unchanged raw values.`"by.sd"` scales by the standard deviation of the data and centers around zero. `"by.range"` rescales the range of the data to the interval from 0 to 1. Defaults to `"as_is"`.
`corr_method`	character string with the correlation method passed to `stats::cor()`. Used for the `.corr` variable appended to the `tidy_corr` dataset and passed on to `lotri_corrtext()`/ `utri_corrtext()` layers. Can be one of `"pearson"`, `"kendall"` and `"spearman"`. Defaults to `"pearson"`.
`corr_group`	`NULL` or the name of a numeric variable in `data`. If a grouping variable is specified, `.corr` will be calculated separately for each of these groups (which may be useful for conditional coloring). Defaults to `NULL`.
`mutates`	(Optional) list of named quosures created with rlang::quos(). Can be any expressions that specify changes to the `tidy_corrm` dataset after reshaping, using regular `dplyr::mutate()` syntax. Defaults to `NULL` (no `mutate` operations on the raw data).
`bg_dia`	(Optional) background color specification for the diagonal panels. Either a character string with a hexadecimal color code, a character string specifying a color name in colors, or an integer specifying a position in palette. The default value of `NULL` uses the standard background color defined in the current ggplot2 theme.
`bg_lotri`	(Optional) background color specification for the panels in the lower triangle. Either a character string with a hexadecimal color code, a character string specifying a color name in colors, or an integer specifying a position in palette. The default value of `NULL` uses the standard background color defined in the current ggplot2 theme.
`bg_utri`	(Optional) background color specification for the panels in the lower triangle. Either a character string with a hexadecimal color code, a character string specifying a color name in colors, or an integer specifying a position in palette. The default value of `NULL` uses the standard background color defined in the current ggplot2 theme.
`facet_arg`	(Optional) list with additional arguments for the facet_grid() call that defines the structure of the panels of the correlation matrix.

ggcorrm creates the initial correlation plot object containing information about panel placement, correlations, themes etc. Its output is a modified empty ggplot object with appropriate facet and theme specifications. If a tidy_corrm object is supplied as data, it will be directly plotted without invoking tidy_corrm(), else, ggcorrm() passes the raw data and additional arguments to tidy_corrm() before plotting (see documentation of this function for details).

New layers can be added using standard ggplot2::ggplot_add() syntax, though in most cases it will be more useful to add layers using the corrmorant selector functions which allow to map geoms to a subset of panels on the plot diagonal, lower or upper triangle using dia(), lotri() or utri(), respectively (see examples).

bg_dia, bg_lotri and bg_utri allow to specify different background color settings for the plot diagonal, the lower and the upper triangle of the correlation plot matrix, respectively. All other graphics settings can be modified using regular ggplot2 theme syntax, building upon the corrmorant standard theme (theme_corrm).

facet_arg allows to change the settings in the ggplot2::facet_grid() call underlying the facet structure of a corrmorant plot. This is likely most helpful if you wish to parse facet labels as expressions with facet_arg = list(labeller = "label_parsed").

An object of class ggcorrm containing the reshaped dataset for the correlation plot and an empty ggplot object with appropriate facet and theme specifications.

tidy_corrm() for the preparation of tidy corrmorant datasets
corrmorant() for a fast and easy to use version of ggcorrm()

## Not run: 
if(interactive()){
# correlation matrix for the drosera dataset
ggcorrm(drosera, bg_dia = "grey20") +
  lotri(geom_point(alpha = 0.4)) +
  utri_corrtext() +
  dia_histogram(lower = .3, fill = "grey90", col = 1) +
  dia_names(y_pos = .1, col = "white", size = 3)

# drosera data with conditional coloring by Pearson correlation
ggcorrm(drosera, aes(col = .corr, fill = .corr)) +
  lotri(geom_point(alpha = 0.6)) +
  lotri(geom_smooth(method = "lm", size = 0.3, alpha = 0.6)) +
  utri_corrtext() +
  dia_density(fill = "grey80", col = 1, lower = .4) +
  dia_names(y_pos = .1) +
  scale_color_corr(option = "A", aesthetics = c("fill", "color"))

# correlation separated by species
ggcorrm(drosera, aes(col = species, fill = species),
        rescale = "by_sd", bg_dia = "grey95") +
  lotri(geom_point(alpha = 0.4)) +
  lotri(geom_smooth(col = 1, method = "lm"))  +
  utri_corrtext(nrow = 2) +
  dia_density(col = 1, alpha = 0.5, lower = 0.4) +
  dia_names(y_pos = 0.15)

# using the 'mutates' argument to color diagonal panels by plant organ
ggcorrm(drosera, rescale = "by_sd",
        mutates = quos(organ = ifelse(substr(var_x, 1, 1) == "p",
                                      "Petiole", "Leaf blade"))) +
  lotri(geom_point(alpha = 0.4))+
  utri_corrtext() +
  dia_density(lower = .3,
              mapping = aes(fill = organ)) +
  dia_names(y_pos = .1,
            mapping = aes(col = organ))


# using facet_args and dia_names(parse = TRUE) to parse variable names
data <- matrix(log(1:100), ncol = 5)
ggcorrm(data,
        labels = c("gamma", "beta", "alpha[3]", "phi^2", "B~(cm^2)"),
        facet_arg = list(labeller = "label_parsed")) +
  utri(geom_point()) +
  lotri_corrtext() +
  dia_names(y_pos = 0.5, parse = TRUE)

 }

## End(Not run)