22.1 Using and manipulating palettes in ArchR

ArchR provides a list of color palettes that we have used in the past and find aesthetically pleasing. These are stored in an object called ArchRPalettes. If we inspect the first few entries of this object, you can see the general structure of a palette in ArchR.

ArchRPalettes[1:3]
## $stallion
##         1         2         3         4         5         6         7         8 
## "#D51F26" "#272E6A" "#208A42" "#89288F" "#F47D2B" "#FEE500" "#8A9FD1" "#C06CAB" 
##        19        10        11        12        13        14        15        16 
## "#E6C2DC" "#90D5E4" "#89C75F" "#F37B7D" "#9983BD" "#D24B27" "#3BBCA8" "#6E4B9E" 
##        17        18         9        20 
## "#0C727C" "#7E1416" "#D8A767" "#3D3D3D" 
## 
## $stallion2
##         1         2         3         4         5         6         7         8 
## "#D51F26" "#272E6A" "#208A42" "#89288F" "#F47D2B" "#FEE500" "#8A9FD1" "#C06CAB" 
##        19        10        11        12        13        14        15        16 
## "#E6C2DC" "#90D5E4" "#89C75F" "#F37B7D" "#9983BD" "#D24B27" "#3BBCA8" "#6E4B9E" 
##        17        18         9 
## "#0C727C" "#7E1416" "#D8A767" 
## 
## $calm
##         1         2         3         4         5         6         7         8 
## "#7DD06F" "#844081" "#688EC1" "#C17E73" "#484125" "#6CD3A7" "#597873" "#7B6FD0" 
##         9        10        11        12        13        14        15        16 
## "#CF4A31" "#D0CD47" "#722A2D" "#CBC594" "#D19EC4" "#5A7E36" "#D4477D" "#403552" 
##        17        18        19        20 
## "#76D73C" "#96CED5" "#CE54D1" "#C48736"

From this, you can see that a palette is a named vector where the names are numbers, starting at 1. The rationale for this is that we have tried to optimize these color palettes to optimally distinguish discrete variables. For example, if you have 5 clusters that you want to color, you would want to use the 5 most easily distinguished colors from the color palette rather than using the 5 random colors which may not be optimally distinguished. In this way, the first N entries in each ArchR palette represent the 5 colors that we find to be best for representing N groups. Note that (i) we have not necessarily optimized the color palettes in ArchR to be color blind-friendly though we do provide some options which are in this class of palettes and (ii) if you have more groups than the number of colors in the designated palette, R will be forced to interpolate colors (the largest palette that we provide is 20 colors).

In the below examples, we use plotEmbedding() as the example function but the same principles apply to other plotting functions as well.

22.1.1 Using pre-defined ArchR palettes

Probably the most confusing aspect of using palettes in ArchR is that some functions that ask for a color palette (for ex. plotEmbedding() or plotTrajectory()) have three parameters that can be manipulated: discreteSet, continuousSet, and pal. Here, discreteSet and continuousSet are used to select pre-defined palettes from ArchRPalettes which are discussed in this section. pal, on the other hand, accepts custom palettes that override the default ArchR palette for a given plot.

Certain types of matrices in ArchR have been assigned a default color scheme. For example, if we do not specify a color palette for continuousSet, the default for GeneScoreMatrix will be “horizonExtra” and the default for other types of matrices will be “solarExtra”:

plotEmbedding(
    ArchRProj = projHeme5,
    embedding = "UMAP",
    colorBy = "GeneScoreMatrix",
    name = "CD14",
    size = 1,
    sampleCells = NULL,
    baseSize = 10,
    plotAs = "points")
## Getting ImputeWeights
## No imputeWeights found, returning NULL
## ArchR logging to : ArchRLogs/ArchR-plotEmbedding-371b074f35ae1-Date-2022-12-23_Time-10-27-31.log
## If there is an issue, please report to github with logFile!
## Getting UMAP Embedding
## ColorBy = GeneScoreMatrix
## Getting Matrix Values...
## 2022-12-23 10:27:34 :
## 
## Plotting Embedding
## 1 
## ArchR logging successful to : ArchRLogs/ArchR-plotEmbedding-371b074f35ae1-Date-2022-12-23_Time-10-27-31.log

However, we can change the color palette to another pre-defined palette in ArchRPalettes by passing the name of that palette to continuousSet (e.g. “whitePurple”). Note that because this data is continuous data, we must use continuousSet and manipulating discreteSet would have no effect.

plotEmbedding(
    ArchRProj = projHeme5,
    embedding = "UMAP",
    colorBy = "GeneScoreMatrix",
    name = "CD14",
    continuousSet = "whitePurple",
    size = 1,
    sampleCells = NULL,
    baseSize = 10,
    plotAs = "points")
## Getting ImputeWeights
## No imputeWeights found, returning NULL
## ArchR logging to : ArchRLogs/ArchR-plotEmbedding-371b06c8266b5-Date-2022-12-23_Time-10-27-40.log
## If there is an issue, please report to github with logFile!
## Getting UMAP Embedding
## ColorBy = GeneScoreMatrix
## Getting Matrix Values...
## 2022-12-23 10:27:43 :
## 
## Plotting Embedding
## 1 
## ArchR logging successful to : ArchRLogs/ArchR-plotEmbedding-371b06c8266b5-Date-2022-12-23_Time-10-27-40.log

If instead we are plotting discrete data, for example “Clusters”, the default color scheme will be “stallion”.

plotEmbedding(
    ArchRProj = projHeme5,
    embedding = "UMAP",
    colorBy = "cellColData",
    name = "Clusters",
    size = 1,
    sampleCells = NULL,
    baseSize = 10,
    plotAs = "points")
## ArchR logging to : ArchRLogs/ArchR-plotEmbedding-371b023eb01f1-Date-2022-12-23_Time-10-27-48.log
## If there is an issue, please report to github with logFile!
## Getting UMAP Embedding
## ColorBy = cellColData
## Plotting Embedding
## 1 
## ArchR logging successful to : ArchRLogs/ArchR-plotEmbedding-371b023eb01f1-Date-2022-12-23_Time-10-27-48.log

As above, we can change the color scheme used for this discrete data by passing the name of one of the pre-defined color palettes in ArchRPalettes to discreteSet:

plotEmbedding(
    ArchRProj = projHeme5,
    embedding = "UMAP",
    colorBy = "cellColData",
    name = "Clusters",
    discreteSet = "kelly",
    size = 1,
    sampleCells = NULL,
    baseSize = 10,
    plotAs = "points")
## ArchR logging to : ArchRLogs/ArchR-plotEmbedding-371b04db94bb-Date-2022-12-23_Time-10-27-52.log
## If there is an issue, please report to github with logFile!
## Getting UMAP Embedding
## ColorBy = cellColData
## Plotting Embedding
## 1 
## ArchR logging successful to : ArchRLogs/ArchR-plotEmbedding-371b04db94bb-Date-2022-12-23_Time-10-27-52.log

22.1.2 Using custom palettes in ArchR

The pal argument allows for the use of custom palettes in most plotting functions. The format of a custom palette is very specific and if you fail to follow this format, it will not work. Effectively, the input to pal must look exactly like the output of paletteDiscrete() for discrete data or paletteContinuous() for continuous data.

22.1.2.1 For discrete data

paletteDiscrete(values = projHeme5$Clusters, set = "kelly")
##        C1        C2        C3        C4        C5        C6        C7        C8 
## "#FFB300" "#803E75" "#FF6800" "#A6BDD7" "#C10020" "#CEA262" "#817066" "#007D34" 
##        C9       C10       C11       C12 
## "#F6768E" "#00538A" "#FF7A5C" "#53377A"

Thus for discrete data, you can see that pal needs to be a named vector of colors where each color is named for the corresponding group (e.g. "C1" = "#F97070"). We can create our own custom palette and pass it to plotEmbedding() to customize the coloration of our clusters:

disc_pal <- c(
  "C1" = "#F97070",
  "C2" = "#D60000",
  "C3" = "#7F0303",
  "C4" = "#F97E2B",
  "C5" = "#FFE600",
  "C6" = "#7BE561",
  "C7" = "#19891E",
  "C8" = "#20C4AC",
  "C9" = "#83A4FF",
  "C10" = "#262C6B",
  "C11" = "#7C0EDD",
  "C12" = "#DB65D2")

plotEmbedding(
    ArchRProj = projHeme5,
    embedding = "UMAP",
    colorBy = "cellColData",
    name = "Clusters",
    pal = disc_pal,
    size = 1,
    sampleCells = NULL,
    baseSize = 10,
    plotAs = "points")
## ArchR logging to : ArchRLogs/ArchR-plotEmbedding-371b0d040774-Date-2022-12-23_Time-10-27-56.log
## If there is an issue, please report to github with logFile!
## Getting UMAP Embedding
## ColorBy = cellColData
## Plotting Embedding
## 1 
## ArchR logging successful to : ArchRLogs/ArchR-plotEmbedding-371b0d040774-Date-2022-12-23_Time-10-27-56.log

22.1.2.2 For continuous data

paletteContinuous(set = "comet", n = 10)

Thus for continuous data, you can see that pal is just a vector of colors. You can create this vector however you wish but here is an example:

cont_pal <- colorRampPalette(c("blue","white","red"))

plotEmbedding(
    ArchRProj = projHeme5,
    embedding = "UMAP",
    colorBy = "GeneScoreMatrix",
    name = "CD14",
    pal = cont_pal(256),
    size = 1,
    sampleCells = NULL,
    baseSize = 10,
    plotAs = "points")
## Getting ImputeWeights
## No imputeWeights found, returning NULL
## ArchR logging to : ArchRLogs/ArchR-plotEmbedding-371b0644c8687-Date-2022-12-23_Time-10-28-00.log
## If there is an issue, please report to github with logFile!
## Getting UMAP Embedding
## ColorBy = GeneScoreMatrix
## Getting Matrix Values...
## 2022-12-23 10:28:02 :
## 
## Plotting Embedding
## 1 
## ArchR logging successful to : ArchRLogs/ArchR-plotEmbedding-371b0644c8687-Date-2022-12-23_Time-10-28-00.log