-
Notifications
You must be signed in to change notification settings - Fork 11
/
Copy pathREADME.Rmd
194 lines (143 loc) · 8.35 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
---
output:
github_document:
keep_html: true
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
library(thematic)
knitr::opts_chunk$set(
message = FALSE,
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "80%",
fig.align = 'center',
fig.width = 6,
fig.asp = 0.618, # 1 / phi
fig.show = "hold",
fig.retina = 2
)
set.seed(1234)
```
# thematic <a href='https://rstudio.github.io/thematic/'><img src='man/figures/logo.png' align="right" height="138.5" style="margin:10px;" /></a>
<!-- badges: start -->
[](https://github.com/rstudio/thematic)
[](https://CRAN.R-project.org/package=thematic)
<!-- badges: end -->
Simplified theming of `{ggplot2}`, `{lattice}`, and `{base}` R graphics. In addition to providing a [centralized approach](https://rstudio.github.io/thematic/articles/custom.html) to styling R graphics, `{thematic}` also enables [automatic styling](https://rstudio.github.io/thematic/articles/auto.html) of R plots in Shiny, R Markdown, and RStudio.
## Installation
Install the stable release of `{thematic}` on [CRAN](https://CRAN.R-project.org) with:
``` r
install.packages("thematic")
```
[Auto theming in Shiny](https://rstudio.github.io/thematic/articles/auto.html#shiny) requires `{shiny}` 1.5.0 or higher:
```r
install.packages("shiny")
```
[Auto theming in R Markdown](https://rstudio.github.io/thematic/articles/auto.html#rmd) requires `{rmarkdown}` 2.7 or higher:
```r
install.packages("rmarkdown")
```
Using themes with [custom fonts](https://rstudio.github.io/thematic/articles/fonts.html) works best if you have `{showtext}` and/or `{ragg}` installed.
```r
install.packages("showtext")
install.packages("ragg")
```
## Overview
`{thematic}`'s [auto theming](https://rstudio.github.io/thematic/articles/auto.html) gives R plots the ability to style themselves inside [Shiny](#shiny) (via CSS), [RStudio](#rstudio) (via [RStudio themes](https://support.posit.co/hc/en-us/articles/115011846747-Using-Themes-in-the-RStudio-IDE)), and [R Markdown](#rmarkdown) (via [`{bslib}`](https://rstudio.github.io/bslib/)).
### Shiny {#shiny}
Call `thematic_shiny()` before launching a Shiny app to enable `{thematic}` for every `plotOutput()` inside the app. If no values are provided to `thematic_shiny()`, each `plotOutput()` uses the app's CSS colors to inform new R plotting defaults. If the app uses [Google Fonts](https://fonts.google.com/) (and you have `{showtext}` and/or `{ragg}` installed), you may safely provide `font = "auto"` to `thematic_shiny()`, which also translates CSS fonts to R. Here's an example with the [Pacifico](https://fonts.google.com/specimen/Pacifico) font:
```r
library(shiny)
library(ggplot2)
library(thematic)
# In order for auto/custom fonts to work properly, you'll want
# either the ragg (or showtext) package installed
library(ragg)
# If you want `{ragg}` to handle the font rendering in a Shiny app
options(shiny.useragg = TRUE)
# Call thematic_shiny() prior to launching the app, to change
# R plot theming defaults for all the plots generated in the app
thematic_shiny(font = "auto")
ui <- fluidPage(
# bslib makes it easy to customize CSS styles for things
# rendered by the browser, like tabsetPanel()
# https://rstudio.github.io/bslib
theme = bslib::bs_theme(
bg = "#002B36", fg = "#EEE8D5", primary = "#2AA198",
# bslib also makes it easy to import CSS fonts
base_font = bslib::font_google("Pacifico")
),
tabsetPanel(
type = "pills",
tabPanel("ggplot", plotOutput("ggplot")),
tabPanel("lattice", plotOutput("lattice")),
tabPanel("base", plotOutput("base"))
)
)
server <- function(input, output) {
output$ggplot <- renderPlot({
ggplot(mtcars, aes(wt, mpg, label = rownames(mtcars), color = factor(cyl))) +
geom_point() +
ggrepel::geom_text_repel()
})
output$lattice <- renderPlot({
lattice::show.settings()
})
output$base <- renderPlot({
image(volcano, col = thematic_get_option("sequential"))
})
}
shinyApp(ui, server)
```
```{r, echo = FALSE, out.width="90%"}
knitr::include_graphics("man/figures/auto-before.png")
```
```{r, echo = FALSE, out.width="90%"}
knitr::include_graphics("man/figures/auto-after.png")
```
### RStudio {#rstudio}
Call `thematic_on()` before generating plots inside RStudio to have all subsequent plots shown in the "Plots" viewing pane to reflect your RStudio theme. Note that `thematic_on()` enables `{thematic}` for the remainder of the R session, but you can use `thematic_off()` to disable ([or `thematic_theme()` for one-off use of `{thematic}`](https://rstudio.github.io/thematic/articles/scope.html#one-time-use)). Here's an example of how `{thematic}` can intelligently adapt each plot to the current RStudio theme:
```{r, echo = FALSE, out.width="100%"}
knitr::include_graphics("https://i.imgur.com/Bvbdn2B.gif")
```
### R Markdown {#rmarkdown}
Call `thematic_rmd()` before generating plots inside R Markdown to have all subsequent plots within the document reflect the relevant theme. In a static (i.e., non-`runtime: shiny`) R Markdown context, auto-theming only works with [`{bslib}`-powered `rmarkdown::html_document()`](https://rstudio.github.io/bslib/#r-markdown-usage) (as in the example below), but in other situations you may also [provide colors and fonts](#custom) explicitly to `thematic_rmd()`.
```{r, echo = FALSE, out.width="100%"}
knitr::include_graphics("vignettes/html-document.svg")
```
### Custom theming {#custom}
By default, `{thematic}` attempts to detect the relevant background, foreground, and accent colors. However, you may also specify these settings more directly by providing relevant color and fonts directly to `thematic_on()` (or `thematic_shiny()`/`thematic_rmd()`).
```{r ggrepel, warning = FALSE}
library(ggplot2)
thematic::thematic_on(bg = "#222222", fg = "white", accent = "#0CE3AC", font = "Oxanium")
ggp <- ggplot(mtcars, aes(wt, mpg, label = rownames(mtcars), color = factor(cyl))) +
geom_point() +
ggrepel::geom_text_repel()
ggp
```
`{thematic}` works by setting new global defaults that can always be overridden with plot-specific `theme()`-ing code:
```{r ggrepel2, warning = FALSE}
ggp + theme(text = element_text(colour = "purple"))
```
To use a "complete" `{ggplot2}` theme with `{thematic}` (e.g., `theme_bw()`, `theme_minimal()`, etc), use `theme_set()` to set the theme globally. This way `{thematic}` has the opportunity to preserve the complete theme's styling semantics when changing global defaults (e.g., `theme_bw()` uses the same fill color for the panel and plot background, which is semantically different from the `theme_gray()` default):
```{r ggrepel3, warning = FALSE}
theme_set(theme_bw())
ggp
```
In addition to setting new defaults for main colors and fonts, `{thematic}` also sets defaults for `qualitative` (and `sequential`) colorscales. See the [custom themes article](https://rstudio.github.io/thematic/articles/custom.html) to learn more about how to customize those defaults.
## Learn more
* See the [auto theming article](https://rstudio.github.io/thematic/articles/auto.html) to gain a more detailed understanding of how auto theming make styling R plots easier in Shiny, R Markdown, and RStudio.
* See the [custom themes article](https://rstudio.github.io/thematic/articles/custom.html) for more on `{thematic}`'s theming options as well as how they interact with `{ggplot2}`, `{lattice}`, and `{base}`.
* See the [fonts article](https://rstudio.github.io/thematic/articles/fonts.html) for more on using Google Fonts with `{thematic}`.
* See the [scoping article](https://rstudio.github.io/thematic/articles/scope.html) for more about scoping `{thematic}` to individual plots.
## Run some examples
Below is a link to an **RStudio Cloud** instance with some ready to run `{thematic}` examples:
<div>
<a href="https://rstudio.cloud/project/1208127" target="_blank">
<img src="man/figures/thematic-test-drive.svg" alt="RStudio Cloud Example" height="80px" style="display: block; margin: 0 auto;">
</a>
</div>
## Code of Conduct
`{thematic}` is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). By [contributing](https://github.com/rstudio/thematic/blob/main/CONTRIBUTING.md) to this project, you agree to abide by its terms.