|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +ggthemes is an R package that provides extra themes, scales, and geoms for ggplot2. It replicates the look of plots from various sources including The Economist, FiveThirtyEight, Edward Tufte, Stephen Few, Stata, Excel, Wall Street Journal, Tableau, and more. |
| 8 | + |
| 9 | +## Development Commands |
| 10 | + |
| 11 | +### Building and Testing |
| 12 | +```bash |
| 13 | +# Full build (generates docs, site, and data) |
| 14 | +make build |
| 15 | + |
| 16 | +# Run package checks |
| 17 | +make test |
| 18 | +# Or directly: |
| 19 | +Rscript -e 'devtools::check()' |
| 20 | + |
| 21 | +# Generate documentation |
| 22 | +make docs |
| 23 | +# Or directly: |
| 24 | +Rscript -e 'devtools::document()' |
| 25 | + |
| 26 | +# Run linter |
| 27 | +make lint |
| 28 | +# Or directly: |
| 29 | +Rscript -e 'devtools::lint()' |
| 30 | + |
| 31 | +# Run code styling |
| 32 | +make style |
| 33 | +# Or directly: |
| 34 | +Rscript scripts/style.R |
| 35 | +``` |
| 36 | + |
| 37 | +### Building Package Data |
| 38 | +```bash |
| 39 | +# Rebuild package data from YAML/XML theme definitions |
| 40 | +make data |
| 41 | +# Or directly: |
| 42 | +Rscript data-raw/build.R |
| 43 | +``` |
| 44 | + |
| 45 | +### Documentation Site |
| 46 | +```bash |
| 47 | +# Build pkgdown site |
| 48 | +make site |
| 49 | +# Or directly: |
| 50 | +Rscript -e 'pkgdown::build_site()' |
| 51 | +``` |
| 52 | + |
| 53 | +### README |
| 54 | +```bash |
| 55 | +# Regenerate README.md from README.Rmd |
| 56 | +Rscript -e 'knitr::knit("README.Rmd", output = "README.md", quiet = TRUE)' |
| 57 | +``` |
| 58 | + |
| 59 | +### Running Tests |
| 60 | +```bash |
| 61 | +# Run all tests |
| 62 | +Rscript -e 'devtools::test()' |
| 63 | + |
| 64 | +# Run specific test file |
| 65 | +Rscript -e 'testthat::test_file("tests/testthat/test-economist.R")' |
| 66 | +``` |
| 67 | + |
| 68 | +## Commit Conventions |
| 69 | + |
| 70 | +This project uses [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages. |
| 71 | + |
| 72 | +### Format |
| 73 | +``` |
| 74 | +<type>[optional scope]: <description> |
| 75 | +
|
| 76 | +[optional body] |
| 77 | +
|
| 78 | +[optional footer(s)] |
| 79 | +``` |
| 80 | + |
| 81 | +### Types |
| 82 | +- **feat**: A new feature |
| 83 | +- **fix**: A bug fix |
| 84 | +- **docs**: Documentation only changes |
| 85 | +- **style**: Changes that don't affect code meaning (formatting, missing semicolons, etc.) |
| 86 | +- **refactor**: Code change that neither fixes a bug nor adds a feature |
| 87 | +- **test**: Adding missing tests or correcting existing tests |
| 88 | +- **chore**: Changes to build process or auxiliary tools |
| 89 | + |
| 90 | +### Examples |
| 91 | +``` |
| 92 | +feat: add solarized dark theme variant |
| 93 | +fix: correct color palette for economist theme |
| 94 | +docs: update README with new theme examples |
| 95 | +test: add visual regression tests for tufte theme |
| 96 | +chore: update pkgdown configuration |
| 97 | +``` |
| 98 | + |
| 99 | +## Architecture |
| 100 | + |
| 101 | +### Code Organization |
| 102 | + |
| 103 | +**R/**: Main source files organized by theme/functionality |
| 104 | +- Each major theme has its own file (e.g., `economist.R`, `tufte.R`, `fivethirtyeight.R`) |
| 105 | +- Each file typically contains: |
| 106 | + - Color palette function (e.g., `economist_pal()`) |
| 107 | + - Scale functions for both color/fill (e.g., `scale_color_economist()`, `scale_fill_economist()`) |
| 108 | + - Theme function (e.g., `theme_economist()`) |
| 109 | +- `utils.R`: Shared utilities including `check_pal_n()`, `get_colors()`, and the `%||%` operator |
| 110 | +- `geom-*.R`: Custom geoms like `geom_rangeframe()` and `geom_tufteboxplot()` |
| 111 | +- `stat-*.R`: Custom stats like `stat_fivenumber()` |
| 112 | +- `base.R`: Contains `theme_foundation()`, the base theme that many other themes build upon |
| 113 | + |
| 114 | +**data-raw/**: Data generation and theme definitions |
| 115 | +- `build.R`: Master script that loads all theme data from YAML/XML files and builds the `ggthemes_data` object |
| 116 | +- `theme-data/`: YAML and XML files defining colors, shapes, and palettes for each theme |
| 117 | +- The build process converts these into tibbles stored in `ggthemes_data` |
| 118 | + |
| 119 | +**ggthemes_data Structure**: A named list containing theme-specific data (colors, palettes, shapes) accessed throughout the package. Each theme has its own nested structure within this object. |
| 120 | + |
| 121 | +### Theme Implementation Pattern |
| 122 | + |
| 123 | +Most themes follow this structure: |
| 124 | + |
| 125 | +1. **Palette function** (`*_pal()`): Returns a function that generates n colors |
| 126 | + - Typically checks n against max_n using `check_pal_n()` |
| 127 | + - Returns colors from `ggthemes_data` based on the requested number |
| 128 | + |
| 129 | +2. **Scale functions**: Wrappers around ggplot2's discrete_scale() or continuous_scale() |
| 130 | + - `scale_color_*()` and `scale_colour_*()` (both spellings supported) |
| 131 | + - `scale_fill_*()` |
| 132 | + |
| 133 | +3. **Theme function** (`theme_*()`): Defines complete plot appearance |
| 134 | + - Usually starts with `theme_foundation()` or another base theme |
| 135 | + - Customizes elements using `theme()` with `element_*()` functions |
| 136 | + |
| 137 | +### Data Loading System |
| 138 | + |
| 139 | +The `data-raw/build.R` script: |
| 140 | +1. Creates a new environment `ggthemes_data` |
| 141 | +2. For each theme, defines a `load_*()` function that: |
| 142 | + - Reads YAML/XML from `data-raw/theme-data/` |
| 143 | + - Converts to tibbles using `map_dfr()` and `as_tibble()` |
| 144 | + - For shapes, converts UTF-8 characters to pch codes |
| 145 | +3. Saves the final list using `usethis::use_data(ggthemes_data, overwrite = TRUE)` |
| 146 | + |
| 147 | +### Testing Strategy |
| 148 | + |
| 149 | +Tests use: |
| 150 | +- **vdiffr**: Visual regression testing via `expect_doppelganger()` helper in `helper-vdiffr.R` |
| 151 | +- Standard testthat expectations for palette functions |
| 152 | +- Tests are organized by theme/feature (one test file per major component) |
| 153 | + |
| 154 | +### Code Style |
| 155 | + |
| 156 | +- Uses tidyverse style enforced by styler (see `.lintr` for configuration) |
| 157 | +- Line length limit: 120 characters |
| 158 | +- Some example files are excluded from linting/styling (see `.lintr` and `scripts/style.R`) |
| 159 | + |
| 160 | +## Key Concepts |
| 161 | + |
| 162 | +**theme_foundation()**: Located in `base.R`, this is the minimal base theme that other themes extend. It sets basic defaults for all ggplot2 elements. |
| 163 | + |
| 164 | +**Color Extraction**: The `get_colors()` utility in `utils.R` filters `ggthemes_data` by color names and extracts hex values. |
| 165 | + |
| 166 | +**Shape Encoding**: Shapes use negative integers as pch codes, converted from UTF-8 using `utf_8_to_pch()` in `data-raw/build.R`. |
| 167 | + |
| 168 | +**README Generation**: README.md is auto-generated from README.Rmd and should never be edited directly. The first line of README.md indicates this. |
0 commit comments