Skip to content

Commit e8350a1

Browse files
pwwangpwwang
committed
docs: enhance documentation for color palette customization and NA handling in plots
1 parent fdf44ff commit e8350a1

1 file changed

Lines changed: 185 additions & 0 deletions

File tree

‎vignettes/articles/basic-design.Rmd‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@ title: "Basic Design Of The Plots"
33
---
44

55
## Color palettes
6+
7+
### Available color palettes
8+
69
The package provides a set of color palettes that are widely used. They are from different packages or used in different tools, including:
710

811
- `viridis` from the [`viridis`][1] package
@@ -38,6 +41,117 @@ See also the following documentation for more details:
3841
- [`show_palettes`](../reference/show_palettes.html)
3942
- [`palette_this`](../reference/palette_this.html)
4043

44+
### Using `palette` and `palcolor` arguments to control the colors in the plots
45+
46+
Most plotting functions in `plotthis` support two arguments to control colors: `palette` and `palcolor`. These arguments provide flexible color customization while maintaining consistency with predefined palettes.
47+
48+
#### The `palette` argument
49+
50+
The `palette` argument specifies which predefined color palette to use. You can view all available palettes with `show_palettes()`. For example:
51+
52+
```r
53+
# Use the "Spectral" palette
54+
BarPlot(data = iris, x = "Species", y = "Petal.Length", palette = "Spectral")
55+
56+
# Use the "nejm" palette from ggsci
57+
BarPlot(data = iris, x = "Species", y = "Petal.Length", palette = "nejm")
58+
```
59+
60+
The palette serves as the foundation for color generation. Colors are automatically assigned based on the number of categories or the range of continuous values in your data.
61+
62+
#### The `palcolor` argument
63+
64+
The `palcolor` argument allows you to override specific colors from the palette. The behavior differs for discrete and continuous color scales:
65+
66+
##### For discrete colors (categorical data)
67+
68+
Use a **named vector** where names correspond to categories in your data. The function will use the palette as the base and replace only the specified colors:
69+
70+
```r
71+
# Replace specific category colors
72+
BarPlot(
73+
data = iris,
74+
x = "Species",
75+
y = "Petal.Length",
76+
palette = "Paired",
77+
palcolor = c("setosa" = "red", "versicolor" = "blue")
78+
)
79+
# "virginica" will still use the color from the "Paired" palette
80+
```
81+
82+
##### For continuous colors (numeric data)
83+
84+
Use a **positional vector** where `NA` values indicate positions to keep from the palette, and non-NA values replace specific positions. The replacement happens **evenly distributed** across the base palette colors:
85+
86+
```r
87+
data(dim_example)
88+
FeatureDimPlot(
89+
data = dim_example,
90+
features = "stochasticbasis_1",
91+
palette = "Spectral",
92+
# The colors will be evenly replace across the palette based on the number of custom colors provided
93+
# Here are the colors that will be used to generate the ramp colors:
94+
# "red" "#3288BD" "#66C2A5" "pink" "#E6F598" "#FFFFBF"
95+
# "#FEE08B" "lightblue" "#F46D43" "#D53E4F" "blue"
96+
# Notice that the 1st, 4th, 8th, and 11th colors in the palette are replaced
97+
palcolor = c("red", "pink", NA, "lightblue", "blue")
98+
)
99+
```
100+
101+
The positions are calculated evenly across the palette, so:
102+
- With 2 values in `palcolor`: replaces first and last colors
103+
- With 3 values: replaces first, middle, and last colors
104+
- With 4 values: replaces at positions 1, 2, 4, and 5 (for a 5-color palette)
105+
106+
This approach ensures smooth color transitions while allowing you to control the endpoints and key intermediate colors.
107+
108+
#### Customizing NA colors
109+
110+
You can specify the color for `NA` values using the `"NA"` key in `palcolor`**
111+
112+
```r
113+
data <- data.frame(x = c("A", NA, "B", "C"), y = c(1, 2, 3, 4))
114+
BarPlot(
115+
data = data,
116+
x = "x", y = "y",
117+
palette = "Paired",
118+
palcolor = c("A" = "red", "NA" = "orange"),
119+
# NA values by default will be dropped
120+
keep_na = TRUE
121+
)
122+
```
123+
124+
#### Complete example
125+
126+
Here's a comprehensive example showing how `palette` and `palcolor` work together:
127+
128+
```r
129+
library(plotthis)
130+
131+
# Sample data with NA values
132+
data <- data.frame(
133+
category = c("A", "B", "C", "D", NA, "A", "B", "C", "D", NA),
134+
value = c(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
135+
)
136+
137+
# Use palette as base, override specific categories, and customize NA color
138+
BarPlot(
139+
data = data,
140+
x = "category",
141+
y = "value",
142+
palette = "Paired", # Base palette
143+
# "A" and "C" will use colors from the "Paired" palette
144+
palcolor = c( # Override specific colors
145+
"B" = "#FF5733", # Custom color for "B"
146+
"D" = "#33FF57", # Custom color for "D"
147+
"NA" = "#333333" # Custom color for NA values
148+
),
149+
keep_na = TRUE # Keep NA values in the plot
150+
)
151+
```
152+
153+
This design gives you fine-grained control over your plot colors while maintaining the convenience of predefined palettes.
154+
41155
## Basic implementation of the plotting functions
42156

43157
The plotting functions in `plotthis` are implemented with the following structure:
@@ -163,3 +277,74 @@ GSEAPlot(data)
163277
# Equivalent to
164278
GSEAPlot(data, gene_ranks = gene_ranks, gene_sets = gene_sets)
165279
```
280+
281+
## Handling NA values and unused levels of factors
282+
283+
## NA values
284+
285+
When NA values appear in the grouping variables or category variables that are used to in the plot (x-axis, fill, color, group, etc.), they will be excluded by default. You can use `keep_na` option to control whether and how to keep the NA values.
286+
287+
- `TRUE`: just keep the NA values as they are, and they will be treated as a separate group or category. They will be included in the plot and the legend. The color for the NA values will be `grey80` by default, but you can customize it using the `palcolor` argument (`palcolor = list("NA" = "orange")`).
288+
- `FALSE`: drop the NA values, and they will not be included in the plot or the legend. This is the default behavior.
289+
- `"missing"`: or other character string, will replace the NA values with the specified string, and they will be treated as a separate group or category. They will be included in the plot and the legend. The color for the values will be determined by `palette` and `palcolor` as usual.
290+
291+
See the above section (Using `palette` and `palcolor` arguments to control the colors in the plots) for more details on how to customize the colors for NA values.
292+
293+
## Unused (Empty) levels of factors
294+
295+
When there are unused levels of factors in the grouping variables or category variables that are used to in the plot (x-axis, fill, color, group, etc.), they will be included in the plot by default. You can use `keep_empty` option to control whether and how to keep the unused levels of factors.
296+
297+
`keep_empty` can take 3 values:
298+
299+
- `TRUE`: just keep the unused levels of factors as they are, and they will be treated as separate groups or categories. They will be included in the plot and the legend.
300+
- `FALSE`: drop the unused levels of factors, and they will not be included in the plot or the legend. This is the default behavior.
301+
- `"level"` or `"levels"`: The unused levels of factors will not be plotted (for example, on x-axis), but they will be included when determining the colors for the groups or categories, and they will not be included in the legend. Use `TRUE` if you want to include them in the legend.
302+
303+
When `keep_empty` is `TRUE` or `"level"`, the colors for the unused levels of factors will be determined by `palette` and `palcolor` as usual, even though they are not plotted (they will affect the colors of existing levels).
304+
305+
```r
306+
data <- data.frame(
307+
# C is an unused level
308+
x = factor(c("A", "B", "D"), levels = c("A", "B", "C", "D")),
309+
y = c(1, 2, 3)
310+
)
311+
312+
# Excluded by default
313+
BarPlot(
314+
data = data,
315+
x = "x", y = "y"
316+
)
317+
318+
# Keep the unused level "C"
319+
BarPlot(
320+
data = data,
321+
x = "x", y = "y",
322+
keep_empty = TRUE
323+
)
324+
325+
# Keep the unused level "C" for color assignment but not plotting
326+
BarPlot(
327+
data = data,
328+
x = "x", y = "y",
329+
keep_empty = "level"
330+
)
331+
```
332+
333+
## Variable-level control of keeping NA values and unused levels of factors
334+
335+
The `keep_na` and `keep_empty` arguments can also take a named list to control the behavior for each variable separately. The names of the list should correspond to the variables in the data. For example:
336+
337+
```r
338+
data <- data.frame(
339+
x = factor(c("A", NA, "B", "D"), levels = c("A", "B", "C", "D")),
340+
group = factor(c("G3", "G1", NA, "G3"), levels = c("G1", "G2", "G3")),
341+
y = c(1, 2, 3, 4)
342+
)
343+
344+
BarPlot(
345+
data = data,
346+
x = "x", y = "y", fill_by = "group",
347+
keep_empty = list(x = TRUE, group = "level"),
348+
keep_na = list(x = FALSE, group = TRUE)
349+
)
350+
```

0 commit comments

Comments
 (0)