civilyticsR/README.md

# 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_gitea(
  "Civilytics/civilyticsR",
  gitea_url = "https://gitea.civilytics.org"
)
```

## 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()`.

``` r
library(civilytics)
library(ggplot2)

(ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  theme_civilytics()) |>
  civilytics_logo()
```

## 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 |