netVis_heatmap: Visualization of network using heatmap
In ycl6/scRUtils: Single-Cell Sequencing Analysis Utilities

netVis_heatmap

R Documentation

Visualization of network using heatmap

Description

This function produces heatmap that shows the number of interactions, interaction strength, or communication probabilities of a chosen pathway in a single dataset (defined by ⁠pathway =⁠), as well as showing the differential comparison of the chosen measures between two datasets.

Usage

netVis_heatmap(
  obj,
  comparison = c(1, 2),
  measure = c("count", "weight", "prob"),
  pathway = NULL,
  heatmap_colors = c("#4575b4", "#d73027"),
  heatmap_colors_min = NULL,
  heatmap_colors_max = NULL,
  cluster_rows = FALSE,
  cluster_columns = FALSE,
  row_names_rot = 0,
  column_names_rot = 90,
  fontsize = 9,
  cell_fontsize = 9,
  show_values = TRUE,
  legend_side = "bottom",
  legend_direction = "horizontal",
  legend_title = NULL,
  legend_title_position = "leftcenter",
  legend_width = unit(5, "cm"),
  legend_height = NULL,
  right_anno_width = unit(2, "cm"),
  top_anno_height = unit(2, "cm"),
  anno_colors = c("#66c2a5", "#fc8d62"),
  anno_legend_ncol = 1,
  anno_legend_side = "bottom",
  anno_legend_direction = "horizontal",
  anno_legend_title = "Sample",
  anno_legend_title_position = "leftcenter",
  plot_title = NULL,
  title_prefix = NULL,
  row_title = "Sources (outgoing signaling)",
  draw = TRUE,
  data_only = FALSE
)

Arguments

`obj`	A CellChat object containing one or merged datasets.
`comparison`	A numerical or character vector of length 2, to indicate the datasets for comparison. Default is `c(1, 2)`.
`measure`	Define the measure to plot, `count` shows the number of interactions; `weight` shows the total interaction weights (strength); `prob` shows thecommunication probabilities of a chosen pathway.
`pathway`	A string to indicate the name of signaling networks in the CellChat object. This is required when `measure = "prob"`.
`heatmap_colors`	A character vector to indicate the colours used to generate a colour palette. The first colour provided is used to create a sequential palette for single-data CellChat object. When comparing two datasets, a diverging palette is created to match the max/min values. Default is `c("#4575b4", "#d73027")`.
`heatmap_colors_min`	A numeric value to set the minimum value used to generate the colour palette. Default is `NULL` and is calculated from the data.
`heatmap_colors_max`	A numeric value to set the maximum value used to generate the colour palette. Default is `NULL` and is calculated from the data.
`cluster_rows`	A logical value to indicate whether to cluster on rows. Default is `FALSE`.
`cluster_columns`	A logical value to indicate whether to cluster on columns. Default is `FALSE`.
`row_names_rot`	A numeric value to set the rotation of row names. Default is `0`.
`column_names_rot`	A numeric value to set the rotation of column names. Default is `90`.
`fontsize`	A numeric value to set the overall font size. Default is `9`.
`cell_fontsize`	A numeric value to set the font size of the values in each cell. Default is `9`.
`show_values`	A logical value to indicate whether to show the values in each cell. Default is `TRUE`.
`legend_side`	A string to indicate the side to put heatmap legend. Possible options are `right`, `left`, `bottom`, and `top`. Default is `bottom`.
`legend_direction`	A string to indicate the direction of the heatmap legend. Possible options are `vertical` and `horizontal`. Default is `horizontal`.
`legend_title`	A string to indicate the heatmap legend title. Default is `NULL` and the function will generate a suitable title depending on the selected `measure`.
`legend_title_position`	A string to indicate the position of title relative to the heatmap legend. Possible options are `leftcenter` and `lefttop` for horizontal legend. Vertical legend accepts `topleft`, `topcenter`, `leftcenter-rot` and `lefttop-rot`. Default is `leftcenter`.
`legend_width`	A `unit` object to set the width of the the whole heatmap legend body. It is only used for horizontal continous legend. Default is `unit(5, "cm")`.
`legend_height`	A `unit` object to set the height of the whole heatmap legend body. It is only used for vertical continous legend. Default is `NULL`.
`right_anno_width`	A `unit` object to set the width of the right (row) annotation on the right. Default is `unit(2, "cm")`.
`top_anno_height`	A `unit` object to set the height of the top (column) annotations on the top. Default is `unit(2, "cm")`.
`anno_colors`	A character vector to indicate the colours used to fill the box plots showing the two datasets, or a single colour used to fill the bar plots showing a single dataset. Default is `c("#66c2a5", "#fc8d62")`.
`anno_legend_ncol`	A integer to set the number of columns in the legend grids. Default is `1`.
`anno_legend_side`	A string to indicate the side to put annotation legend. Default is `bottom`.
`anno_legend_direction`	A string to indicate the direction of the annotation legend. Default is `horizontal`.
`anno_legend_title`	A string to indicate the annotation legend title. Default is "Sample".
`anno_legend_title_position`	A string to indicate the position of title relative to the annotation legend. Default is `leftcenter`.
`plot_title`	A string to indicate the plot (column) title. Default is `NULL` and the function will generate a suitable title depending on the selected `measure`.
`title_prefix`	A string to append to the plot (column) title. Default is `NULL`.
`row_title`	A string to indicate the row title. Default is `⁠Sources (outgoing signaling)⁠`.
`draw`	A logical value to indicate whether to draw the heatmap. When `draw = FALSE`, the function retuns a grob (`gTree`) object made with package `grid`. Default is `TRUE`.
`data_only`	A logical value to indicate whether to return a list containing the calculated values. This is useful for users to create their own plots. When `data_only = TRUE`, the function will not plot or return a `gTree` object. Default is `FALSE`.

Details

When showing differential comparison:

Using the default heatmap_colors, the red (or blue) represents increased (or decreased) signaling in the second dataset compared to the first one.
The box plots on the top show the original values of the selected measure from cell groups from the two datasets in each column (incoming signaling).
The box plots on the right show the original values of the selected measure from cell groups from the two datasets in each row (outgoing signaling).

The function offers an alternative method to create heatmap from CellChat object.

Compared to CellChat::netVisual_heatmap function, it offers more controls to the plot aesthetic and offers two output types (defined by ⁠draw =⁠): to plot on device or provide a gTree object. This can be used with other R package such as 'patchwork' (might require warpping gTree object with wrap_elements function), 'cowplot' (with plot_grid function) or 'gridExtra' (with grid.arrange function) to combine multiple heatmaps, or with other type of plot object types such as ggplot into a single graphic.

For users who will like to create their own plots, one can use data_only = TRUE to obtain a list that contains the matrix with the calculated values, and optionally the original values of the selected measure from cell groups from the two datasets when showing differential comparison.

Value

A plot appears on currect plotting device if draw = FALSE. When draw = FALSE, the function retuns a grob (gTree) object made with package grid. When data_only = TRUE, the function retuns list object containing the data values.