mgheatmap {sparrow} | R Documentation

## Creates a "geneset smart" ComplexHeatmap::Heatmap

### Description

Before we get started, note that you probably want to use `mgheatmap2()`.

This function encapsulates many common "moves" you'll make when trying to make a heatmap, especially if you are trying to show geneset activity across a panel of samples.

NOTE: this function will almost certainly reorder the rows of the input matrix. If you are concatentating Heatmap objects together horizontally (ie. you if you want to use a rowAnnotation along side the returned heatmap), you must reorder the rows of the annotation data.frame, ie. `ranno.df <- ranno.df[rownames(out@matrix),]`

### Usage

    mgheatmap(
      x,
      gdb = NULL,
      col = NULL,
      aggregate.by = c("none", "ewm", "ewz", "zscore"),
      split = TRUE,
      scores = NULL,
      gs.order = NULL,
      name = NULL,
      rm.collection.prefix = TRUE,
      rm.dups = FALSE,
      recenter = FALSE,
      rescale = FALSE,
      center = TRUE,
      scale = TRUE,
      rename.rows = NULL,
      zero_center_colramp = NULL,
      zlim = NULL,
      transpose = FALSE,
      ...
    )

### Arguments

`x` | the data matrix
`gdb` | `GeneSetDb` object that holds the genesets to plot. Defaults to `NULL`, which will plot all rows in `x`.
`col` | a colorRamp(2) function
`aggregate.by` | the method used to generate single-sample geneset scores. Default is `none` which plots heatmap at the gene level
`split` | introduce row-segmentation based on genesets or collections? Defaults is `TRUE` which will create split heatmaps based on collection if `aggregate.by != 'none'`, or based on gene sets if `aggregate.by == "none"`.
`scores` | If `aggregate.by != "none"` you can pass in a precomupted `scoreSingleSamples()` result, otherwise one will be computed internally. Note that if this is a `data.frame` of pre-computed scores, the `gdb` is largely irrelevant (but still required).
`gs.order` | This is experimental, and is here to help order the order of the genesets (or genesets collection) in a different way than the default. By default, `gs.order = NULL` and genesets are enumerated in alphabetical in the heatmap. You can pass in a character vector that will dictate the order of the genesets displayed in the heatmap. Currently this only matches against the `"name"` value of the geneset and probably only works when `split = TRUE`. We will support `colleciton,name` tuples soon. This can be a superset of the names found in `gdb`. As of ComplexHeatmap v2 (maybe earlier versions), this doesn't really work when `cluster_rows = TRUE`.
`name` | passed down to `ComplexHeatmap::Heatmap()`
`rm.collection.prefix` | When `TRUE` (default), removes the collection name from the genesets annotated on the heatmap.
`rm.dups` | if `aggregate.by == 'none'`, do we remove genes that appear in more than one geneset? Defaults to `FALSE`
`recenter` | do you want to mean center the rows of the heatmap matrix prior to calling `ComplexHeatmap::Heatmap()`?
`rescale` | do you want to standardize the row variance to one on the values of the heatmap matrix prior to calling `ComplexHeatmap::Heatmap()`?
`center, scale` | boolean parameters passed down into the the single sample gene set scoring methods defined by `aggregate.by`
`rename.rows` | defaults to `NULL`, which induces no action. Specifying a paramter here assumes you want to rename the rows of the heatmap. Please refer to the "Renaming Rows" section for details.
`zero_center_colramp` | Used to specify the type of color ramp to generate when `col` is `NULL`. By default (`NULL`) we try to guess if we should generate a 0-centered (blue, white, red) color ramp, or an absolute (viridis style) one. The guessing functionality isn't that great, so it doesn't hurt to explicitly set this to `TRUE` or `FALSE`.
`zlim` | Used to control the color saturation of the heatmap when the `col` parameter is not provided. If `NULL`, (default), extreme values (outside the `c(0.025, 0.975)` quantiles) are axed and the colorRamp is based on the remaining value range. If `FALSE`, the range of the colorRamp is defined by the min/max values. Otherwise a length(2) numeric can be supplied. If the values are between `[0,1]`, then we assume this is a quantile range to be calculated. Otherwise the number are assumed to mark the top and bottom of the color scale range you want to use.
`transpose` | Flip display so that rows are columns. Default is `FALSE`.
`...` | parameters to send down to `scoreSingleSamples()`, `ComplexHeatmap::Heatmap()`, `renameRows()` internal `as_matrix()`.

### Details

More info here.

### Value

A `Heatmap` object.

### Renaming Heatmap Rows

This function leverages `renameRows()` so that you can better customize the output of your heatmaps by tweaking its rownames.

If you are plotting a gene-level heatmap (ie. `aggregate.by == "none"``) and the` rownames()`are gene identifiers, but you want the rownames of the heatmap to be gene symbols. You can perform this renaming using the`rename.rows' parameter.

- If `rename.rows` is `NULL`, then nothing is done.

- If `rename.rows` is a `string`, then we assume that `x` has an associated metadata `data.frame` over its rows and that `rename.rows` names one of its columns, ie. `DGEList$genes[[rename.rows]]` or `fData(ExpressionSet)[[rename.rows]]`. The values in that column will be swapped out for `x`'s rownames

- If `rename.rows` is a two-column data.frame, the first column is assumed to be `rownames(x)` and the second is what you want to rename it to.

- When there are duplicates in the renamed rownames, the `rename.duplicates` `...` parameter dictates the behavior. This will happen, for instance, if you are trying to rename the rows of an affy matrix to gene symbols, where we have multiple probe ids for one gene. When `rename.duplicates` is set to `"original"`, one of the rows will get the new name, and the remaning duplicate rows will keep the rownames they came in with. When set to `"make.unique"`, the new names will contain `*.1`, `*.2`, etc. suffixes, as you would get from using `base::make.unique()`.

Maybe you are aggregating the expression scores into geneset scores, and you don't want the rownames of the heatmap to be `collection;;name` (or just `name` when `rm.collection.prefx = TRUE`), you can pass in a two column `data.frame`, where the first column is `collection;name` and the second is the name you want to rename that to. There is an example of this in the "Examples" section here.

### See Also

`mgheatmap2()`

### Examples

    library(ComplexHeatmap)
    vm <- exampleExpressionSet()
    gdb <- exampleGeneSetDb()
    col.anno <- ComplexHeatmap::HeatmapAnnotation(
      df = vm$targets[, c("Cancer_Status", "PAM50subtype")],
      col = list(
        Cancer_Status = c(normal = "grey", tumor = "red"),
        PAM50subtype = c(Basal = "purple", Her2 = "green", LumA = "orange")))
    mgh <- mgheatmap(vm, gdb, aggregate.by = "ewm", split=TRUE,
                     top_annotation = col.anno, show_column_names = FALSE,
                     column_title = "Gene Set Activity in BRCA subset")

    # Maybe you want the rownames of the matrix to use spaces instead of "_"
    rr <- geneSets(gdb)[, "name", drop = FALSE]
    rr$newname <- gsub("_", " ", rr$name)
    mg2 <- mgheatmap(vm, gdb, aggregate.by='ewm', split=TRUE,
                     top_annotation = col.anno, show_column_names = FALSE,
                     column_title = "Gene Set Activity in BRCA subset",
                     rename.rows = rr)

[Package sparrow version 1.0.3 Index]