232 lines
6.4 KiB
Markdown
232 lines
6.4 KiB
Markdown
|
||
# civilytics
|
||
|
||
Brand themes, color palettes, and utility functions for [Civilytics
|
||
Consulting](https://www.civilytics.com). The package provides a complete
|
||
ggplot2 theme system drawn from the Civilytics design system — warm
|
||
paper backgrounds, civic-navy ink, and editorial typography — along with
|
||
10 curated color palettes, logo composition helpers, and data-wrangling
|
||
utilities for public-sector analysis.
|
||
|
||
## Installation
|
||
|
||
Install from the Civilytics Gitea server:
|
||
|
||
``` r
|
||
# install.packages("remotes")
|
||
remotes::install_git("https://gitea.civilytics.org/Civilytics/civilyticsR.git")
|
||
```
|
||
|
||
## Quick start
|
||
|
||
``` r
|
||
library(civilytics)
|
||
library(ggplot2)
|
||
|
||
ggplot(mpg, aes(displ, hwy, colour = class)) +
|
||
geom_point(size = 2.5) +
|
||
scale_color_civilytics() +
|
||
labs(
|
||
title = "Fuel economy by engine displacement",
|
||
subtitle = "Highway MPG vs. engine size for 234 vehicles",
|
||
caption = "Source: EPA fuel economy data (ggplot2::mpg)",
|
||
x = "Engine displacement (litres)",
|
||
y = "Highway MPG"
|
||
) +
|
||
theme_civilytics()
|
||
```
|
||
|
||
<img src="man/figures/README-quickstart-1.png" alt="" width="100%" />
|
||
|
||
## Color palettes
|
||
|
||
The package ships 53 named brand colors in `civilytics_colors` and 10
|
||
curated palettes in `civilytics_palettes`. Use `civilytics_palette()` to
|
||
retrieve colors by name, or pass palettes directly to the ggplot2
|
||
scales.
|
||
|
||
### Palette gallery
|
||
|
||
<img src="man/figures/README-palette-gallery-1.png" alt="" width="100%" />
|
||
|
||
### Using palettes
|
||
|
||
``` r
|
||
# Discrete fill with the qualitative palette
|
||
ggplot(mpg, aes(class, fill = class)) +
|
||
geom_bar(show.legend = FALSE) +
|
||
scale_fill_civilytics() +
|
||
labs(title = "Vehicle counts by class", x = NULL, y = NULL) +
|
||
theme_civilytics(grid = "y")
|
||
```
|
||
|
||
<img src="man/figures/README-palette-usage-1.png" alt="" width="100%" />
|
||
|
||
``` r
|
||
|
||
# Continuous fill with a sequential palette
|
||
ggplot(faithfuld, aes(waiting, eruptions, fill = density)) +
|
||
geom_tile() +
|
||
scale_fill_civilytics("seq_ember", discrete = FALSE) +
|
||
labs(title = "Old Faithful eruption density") +
|
||
theme_civilytics(grid = "none")
|
||
```
|
||
|
||
<img src="man/figures/README-palette-usage-2.png" alt="" width="100%" />
|
||
|
||
## Themes
|
||
|
||
Three theme variants cover the most common output contexts. All share
|
||
the same typographic structure and accept `grid` and `paper_bg`
|
||
parameters.
|
||
|
||
### Editorial (default)
|
||
|
||
The default theme uses a warm paper background with horizontal gridlines
|
||
— an editorial, Pew-style layout.
|
||
|
||
``` r
|
||
base_plot <- ggplot(mpg, aes(displ, hwy)) +
|
||
geom_point(aes(colour = factor(cyl)), size = 2) +
|
||
scale_color_civilytics() +
|
||
labs(
|
||
title = "Engine size vs. highway fuel economy",
|
||
subtitle = "Colored by number of cylinders",
|
||
caption = "Source: ggplot2::mpg",
|
||
colour = "Cylinders",
|
||
x = "Displacement (L)", y = "Highway MPG"
|
||
)
|
||
|
||
base_plot + theme_civilytics()
|
||
```
|
||
|
||
<img src="man/figures/README-theme-editorial-1.png" alt="" width="100%" />
|
||
|
||
### Grid options
|
||
|
||
The `grid` parameter controls which major gridlines are drawn.
|
||
|
||
<img src="man/figures/README-theme-grids-1.png" alt="" width="100%" />
|
||
|
||
### Dark
|
||
|
||
Dark navy background with light text, suitable for presentations or
|
||
dashboards on dark surfaces.
|
||
|
||
``` r
|
||
base_plot + theme_civilytics_dark()
|
||
```
|
||
|
||
<img src="man/figures/README-theme-dark-1.png" alt="" width="100%" />
|
||
|
||
### Slide
|
||
|
||
Transparent background and larger base font (18 pt), sized for Reveal.js
|
||
slides or PowerPoint exports.
|
||
|
||
``` r
|
||
base_plot + theme_civilytics_slide()
|
||
```
|
||
|
||
<img src="man/figures/README-theme-slide-1.png" alt="" width="100%" />
|
||
|
||
### Facets
|
||
|
||
Facet strips use the `paper_2` tint, with the title font.
|
||
|
||
``` r
|
||
ggplot(mpg, aes(displ, hwy)) +
|
||
geom_point(colour = civilytics_colors["navy_600"], size = 1.5) +
|
||
facet_wrap(~class, ncol = 4) +
|
||
labs(
|
||
title = "Highway MPG by vehicle class",
|
||
x = "Displacement (L)", y = "Highway MPG"
|
||
) +
|
||
theme_civilytics(grid = "y")
|
||
```
|
||
|
||
<img src="man/figures/README-theme-facets-1.png" alt="" width="100%" />
|
||
|
||
## Logo utilities
|
||
|
||
Add the Civilytics logo to any ggplot using the pipe-friendly
|
||
`civilytics_logo()` or the lower-level `add_logo()` /
|
||
`make_logo_grob()`. The logo is automatically right-aligned below the
|
||
plot area. Wrap the ggplot chain in parentheses before piping — R’s `|>`
|
||
binds tighter than `+`.
|
||
|
||
### Wordmark on a light plot
|
||
|
||
``` r
|
||
p <- ggplot(mpg, aes(displ, hwy, colour = class)) +
|
||
geom_point(size = 2) +
|
||
scale_color_civilytics() +
|
||
labs(
|
||
title = "Fuel economy by engine displacement",
|
||
caption = "Source: EPA fuel economy data (ggplot2::mpg)",
|
||
x = "Displacement (L)", y = "Highway MPG"
|
||
) +
|
||
theme_civilytics()
|
||
|
||
grid::grid.draw(civilytics_logo(p))
|
||
```
|
||
|
||
<img src="man/figures/README-logo-wordmark-1.png" alt="" width="100%" />
|
||
|
||
### Compact mark
|
||
|
||
Use `type = "mark"` for the compact C-pulse icon instead of the full
|
||
wordmark.
|
||
|
||
``` r
|
||
p2_logo <- ggplot(mpg, aes(displ, hwy, colour = factor(cyl))) +
|
||
geom_point(size = 2) +
|
||
scale_color_civilytics() +
|
||
labs(
|
||
title = "Engine size vs. highway fuel economy",
|
||
colour = "Cylinders",
|
||
x = "Displacement (L)", y = "Highway MPG"
|
||
) +
|
||
theme_civilytics()
|
||
|
||
grid::grid.draw(civilytics_logo(p2_logo, type = "mark"))
|
||
```
|
||
|
||
<img src="man/figures/README-logo-mark-1.png" alt="" width="100%" />
|
||
|
||
### Multi-plot layout with logo
|
||
|
||
Use `add_logo_ga()` to attach a single logo below a row of plots.
|
||
|
||
``` r
|
||
p1 <- ggplot(mpg, aes(class, fill = class)) +
|
||
geom_bar(show.legend = FALSE) +
|
||
scale_fill_civilytics() +
|
||
labs(title = "Vehicle counts", x = NULL, y = NULL) +
|
||
theme_civilytics(grid = "y")
|
||
|
||
p2 <- ggplot(mpg, aes(displ, hwy)) +
|
||
geom_point(colour = civilytics_colors["navy_600"], size = 1.5) +
|
||
labs(title = "Displacement vs. MPG", x = "Displacement (L)", y = "Highway MPG") +
|
||
theme_civilytics(grid = "y")
|
||
|
||
logo <- make_logo_grob()
|
||
grid::grid.draw(add_logo_ga(list(p1, p2), logo))
|
||
```
|
||
|
||
<img src="man/figures/README-logo-multi-1.png" alt="" width="100%" />
|
||
|
||
## Other utilities
|
||
|
||
The package also includes helpers for public-sector data analysis:
|
||
|
||
| Function | Purpose |
|
||
|:---|:---|
|
||
| `pretty_count()` / `pretty_per()` | Format numbers and percentages |
|
||
| `grade_level_to_num()` | Convert grade labels (KG, 01–12) to numeric |
|
||
| `race_short_names()` | Standardize NCES race/ethnicity categories |
|
||
| `get_fips()` / `get_stabbr()` | State FIPS code lookups |
|
||
| `clopper_pearson()` / `agresti_coull_interval()` | Proportion confidence intervals |
|
||
| `match_test()` / `trunc_match()` | Fuzzy join diagnostics |
|
||
| `perturb_count()` / `random_round()` | Privacy-preserving data perturbation |
|