-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME.Rmd
125 lines (90 loc) · 6.9 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
---
output: github_document
---
<!--
####### UUUUUUUU ,ad8888ba, 88b d88 db 88888888ba
####### :UUUUUUU d8"' `"8b 888b d888 d88b 88 "8b
#######. :UUUUUU d8' 88`8b d8'88 d8'`8b 88 ,8P
######## :UUUUU 88 88 `8b d8' 88 d8' `8b 88aaaaaa8P'
#########: :UUU 88 88 `8b d8' 88 d8YaaaaY8b 88""""""'
##########: ' Y8, 88 `8b d8' 88 d8""""""""8b 88
#############:. Y8a. .a8P 88 `888' 88 d8' `8b 88
################ `"Y8888Y"' 88 `8' 88 d8' `8b 88
PROUDLY PRESENTS
88
88 ,d
88 88
,adPPYba, 88,dPYba,,adPYba, ,adPPYYba, 8b,dPPYba, 8b,dPPYba, 88 ,adPPYba, MM88MMM
a8" "" 88P' "88" "8a "" `Y8 88P' "8a 88P' "8a 88 a8" "8a 88
8b 88 88 88 ,adPPPPP88 88 d8 88 d8 88 8b d8 88
"8a, ,aa 88 88 88 88, ,88 88b, ,a8" 88b, ,a8" 88 "8a, ,a8" 88,
`"Ybbd8"' 88 88 88 `"8bbdP"Y8 88`YbbdP"' 88`YbbdP"' 88 `"YbbdP"' "Y888
88 88
88 88
An R package made with ♥ in Chicago by and for CMAP staff.
-->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
fig.width = 7,
fig.asp = 400/670,
fig.retina = 4,
fig.align = "center",
dev = "ragg_png"
)
devtools::load_all()
library(tidyverse)
```
# cmapplot <img src="man/figures/logo.png" align="right" alt="cmapplot logo" width="128" />
<!-- badges: start -->
[](https://github.com/CMAP-REPOS/cmapplot/actions?query=workflow%3AR-CMD-check)
[](https://github.com/CMAP-REPOS/cmapplot/actions?query=workflow%3Apkgdown)
<!-- badges: end -->
This R package provides themes, color scales, and other custom functions for [ggplot2](https://github.com/tidyverse/ggplot2), based on Chicago Metropolitan Agency for Planning (CMAP) design guidelines.
CMAP staff who are interested in using this package, or merely staying in the loop, are encouraged to join the [R team](https://teams.microsoft.com/l/team/19%3ad705bfd7596a4518b588ad529d2367c8%40thread.skype/conversations?groupId=d7bab529-9c30-441e-9db6-4edfdca8202c&tenantId=43b185b9-e6d9-45a5-8e36-4c08dc0ab1a2) in Microsoft Teams and follow the "cmapplot" channel.
## The basics
The cmapplot package contains a few key components:
1. Apply a CMAP theme to ggplots with `theme_cmap()`
2. Easily provide common CMAP plot customizations, such as with custom geoms `geom_recessions()` and `geom_text_lastonly()`
3. Apply CMAP colors using a variety of custom functions (e.g. `cmap_fill_discrete()`)
4. Place the themed plot within a CMAP layout, and export the plot from R if desired with `finalize_plot()`
## Installation
Run the following to install or update cmapplot:
```{r install, eval=FALSE, message=FALSE, warning=FALSE}
## Install current version from GitHub
devtools::install_github("CMAP-REPOS/cmapplot", build_vignettes=TRUE)
## Then load the package as you would any other
library(cmapplot)
```
For more detailed information about installing the package, particularly on a CMAP-issued computer, see [this article](https://cmap-repos.github.io/cmapplot/articles/installation.html).
To install on macOS, users must install [XQuartz](https://www.xquartz.org) before cmapplot can be loaded. (This can be easily accomplished via the [Homebrew](https://brew.sh) package manager with the command `brew install --cask xquartz`.)
**A note about fonts**: The cmapplot package works best when installed on a computer with the Whitney family of fonts installed (specifically the Book, Medium, and Semibold variants). If installed on a computer *without* Whitney, the package will still work, but the fonts will default to your computer's default sans-serif font (probably Arial).
## CMAP theme and colors
The function `theme_cmap()` returns a complete ggplot2 theme that can be added to a ggplot code block (similar to `ggplot2::theme_minimal()` or `ggplot2::theme_bw()`). Additionally, `theme_cmap()` accepts a variety of arguments to additionally customize the theme output. CMAP color functions apply colors from the CMAP color palette to the plot.
```{r theme, message=FALSE}
ggplot(data = pop_and_laborforce_by_age,
aes(x = value,
y = interaction(year, variable, sep = " "),
fill = age)) +
geom_col(position = position_stack(reverse = TRUE)) +
scale_x_continuous(labels = scales::percent) +
theme_cmap(xlab = "Percent",
gridlines = "v",
vline = 0) +
cmap_fill_discrete(palette = "environment")
```
## Finalizing the plot
The function `finalize_plot()` places a ggplot within a frame defined by CMAP design standards. It provides a variety of customization options via arguments, and allows for in-R viewing and/or exporting in various formats.
```{r finalize, message=FALSE}
finalize_plot(title = "Regional population and labor force participation",
caption = "Data from the American Community Survey",
width = 7, height = 4.25)
```
## Additional reading
While this package is designed to make the application of CMAP design standards to plots relatively easy, developing a professional, finished plot in R will require a decent familiarity with the grammar of [ggplot2](ggplot2.tidyverse.org/). Excellent resources in this category already exist:
- The [R graphics cookbook](https://r-graphics.org/) provides accessible examples of how to make almost [any type](https://r-graphics.org/recipe-miscgraph-vectorfield) of plot, as well as how to modify things like [limits, scales](https://r-graphics.org/recipe-axes-range), [coordinate systems](https://r-graphics.org/recipe-axes-polar), and [facets](https://r-graphics.org/recipe-facet-basic).
- The [ggplot2 book](https://ggplot2-book.org/) delves deeper into why and how ggplot2 works the way it does, also with distinct chapters on topics like [scales](https://ggplot2-book.org/scales-guides.html), [coordinate systems](https://ggplot2-book.org/coord.html), [facets](https://ggplot2-book.org/facet.html), etc.
- The [ggplot2](ggplot2.tidyverse.org/) website.
- The [R for Data Science (R4DS)](https://r4ds.had.co.nz/) book, especially the [Graphics for Communication](https://r4ds.had.co.nz/graphics-for-communication.html) chapter.