Describing the `ExperimentColorMap` class

Compiled date: r Sys.Date()

Last edited: 2018-03-08

License: r packageDescription("iSEE")[["License"]]

    collapse = TRUE,
    comment = "#>",
    error = FALSE,
    warning = FALSE,
    message = FALSE,
    crop = NULL
sce <- readRDS('sce.rds')
SCREENSHOT <- function(x, ...) knitr::include_graphics(x)


r Biocpkg("iSEE") coordinates the coloration in every plot via the ExperimentColorMap class [@kra2018iSEE]. Colors for samples or features are defined from column or row metadata or assay values using "colormaps". Each colormap is a function that takes a single integer argument and returns that number of distinct colors. The ExperimentColorMap is a container that stores these functions for use within the iSEE() function. Users can define their own colormaps to customize coloration for specific assays or covariates.

Defining colormaps

Colormaps for continuous variables

For continuous variables, the function will be asked to generate a number of colors (21, by default). Interpolation will then be performed internally to generate a color gradient. Users can use existing color scales like viridis::viridis or heat.colors:

# Coloring for log-counts:
logcounts_color_fun <- viridis::viridis

It is also possible to use a function that completely ignores any arguments, and simply returns a fixed number of interpolation points:

# Coloring for FPKMs:
fpkm_color_fun <- function(n){

Colormaps for categorical variables

For categorical variables, the function should accept the number of levels and return a color per level. Colors are automatically assigned to factor levels in the specified order of the levels.

# Coloring for the 'driver' metadata variable.
driver_color_fun <- function(n){
    RColorBrewer::brewer.pal(n, "Set2")

Alternatively, the function can ignore its arguments and simply return a named vector of colors if users want to specify the color for each level explicitly It is the user's responsibility to ensure that all levels are accounted for^[Needless to say, these functions should not be used as shared or global colormaps.]. For instance, the following colormap function will only be compatible with factors of two levels, namely "Y" and "N":

# Coloring for the QC metadata variable:
qc_color_fun <- function(n){
    qc_colors <- c("forestgreen", "firebrick1")
    names(qc_colors) <- c("Y", "N")

The colormap hierarchy

Specific and shared colormaps

Colormaps can be defined by users at three different levels:

Searching for colors

When queried for a specific colormap of any type (assay, column data, or row data), the following process takes place:

By default, viridis is used as the default continuous colormap, and hcl is used as the default categorical colormap.

Creating the ExperimentColorMap

We store the set of colormap functions in an instance of the ExperimentColorMap class. Named functions passed as assays, colData, or rowData arguments will be used for coloring data in those slots, respectively.

ecm <- ExperimentColorMap(
    assays = list(
        counts = heat.colors,
        logcounts = logcounts_color_fun,
        cufflinks_fpkm = fpkm_color_fun
    colData = list(
        passes_qc_checks_s = qc_color_fun,
        driver_1_s = driver_color_fun
    all_continuous = list(
        assays = viridis::plasma

Users can change the defaults for all assays or column data by modifying the shared colormaps. Similarly, users can modify the defaults for all continuous or categorical data by modifying the global colormaps. This is demonstrated below for the continuous variables:

    all_continuous=list( # shared
    global_continuous=viridis::magma # global


The ExperimentColorMap class offers the following major features:

Detailed examples on the use of ExperimentColorMap objects are available in the documentation ?ExperimentColorMap, as well as below.


Here, we use the allen single-cell RNA-seq data set to demonstrate the use of the ExperimentColorMap class. Using the sce object that we created r Biocpkg("iSEE", vignette="basic.html", label="previously"), we create an iSEE app with the SingleCellExperiment object and the colormap generated above.

app <- iSEE(sce, colormap = ecm)

We run this using runApp to open the app on our browser.


Now, choose to color cells by Column data and select passes_qc_checks_s. We will see that all cells that passed QC (Y) are colored "forestgreen", while the ones that didn’t pass are colored firebrick.

If we color any plot by gene expression, we see that use of counts follows the heat.colors coloring scheme; use of log-counts follows the viridis coloring scheme; and use of FPKMs follows the black-to-yellow scheme we defined in fpkm_color_fun.

Session Info {.unnumbered}

# devtools::session_info()

References {.unnumbered}

Try the iSEE package in your browser

Any scripts or data that you put into this service are public.

iSEE documentation built on Feb. 3, 2021, 2:01 a.m.