wildcat

Modern, customizable beamer and Stata/Python/R themes

View the Project on GitHub aarondwolf/wildcat

Agent Guide: Wildcat Theme System (Stata, R, Python)

Repository context: The upstream repository is https://github.com/aarondwolf/wildcat. The scheme and plotting assets live inside the scheme/ subdirectory of that repo: https://github.com/aarondwolf/wildcat/tree/main/scheme

All paths in this document are described relative to that scheme/ directory.

This guide provides instructions for AI coding agents to:

  1. Download and install the theme files across Stata, R, and Python.
  2. Reference and use them in user scripts and automation workflows.
  3. Customize colors, palettes, and theme names programmatically across all three environments.
  4. Maintain visual parity so graphs across Stata, R, and Python match closely.

1. Quick Summary of Assets by Language

Language Core Assets Example Suite Styling Model Source of Truth / Reference
Stata scheme-wildcat.scheme, color-*.style, wildcat.pkg, stata/make_scheme.do stata/examples.do Stata Graph Scheme & Style definitions Anchored to R ggplot2
R r/theme_wildcat.R, r/theme_nu.R r/examples.r ggplot2 theme functions & discrete scales Primary visual source of truth
Python py/theme_wildcat.py, py/wildcat.mplstyle, py/__init__.py py/examples.py Matplotlib rcParams, cycler, helper functions Anchored to R ggplot2

2. Stata Workflow

A. Downloading & Installing

When working in an agent environment with Stata available:

B. Referencing in Stata Scripts

Once installed:

* Apply scheme globally or per graph:
set scheme wildcat

* Use native Northwestern brand colors directly in graph commands:
twoway (scatter mpg weight, mcolor(nupurple) mlcolor(nudarkorange)) ///
       (lfit mpg weight, lcolor(nupurple%80) lwidth(medthick)), ///
       title("{bf:Mileage vs. Weight}", size(medium) color(wc_title)) ///
       subtitle("Northwestern branding", size(small) color(wc_body)) ///
       note("Source: 1978 Automobile Data", size(vsmall) color(wc_body))

C. Comprehensive Example Script (examples.do)

For a complete demonstration of all 16 publication-grade chart types implemented in Stata, see stata/examples.do. It demonstrates:

D. Customizing Colors & Scheme Name in Stata

Do not manually edit scheme-wildcat.scheme directly; edit and execute stata/make_scheme.do:

  1. Change Theme Name: In stata/make_scheme.do, change:
    local scheme_name   "custom_name"     // Will generate scheme-custom_name.scheme
    local scheme_title  "Custom Theme"
    
  2. Add Custom Brand Colors: Un-comment and define custom RGB strings:
    local myblue   "0 51 102"
    local mygold   "255 199 44"
    local custom_colors myblue mygold
    
  3. Change Discrete Plot Sequence: Update local color1 "myblue’”, local color2 “mygold'", etc.
  4. Compile: Execute do stata/make_scheme.do. It regenerates scheme-<name>.scheme and all corresponding color-<name>.style files.

3. R Workflow (ggplot2)

A. Downloading & Referencing

R packages are often invoked on systems without Git cloning. Agents can load theme_wildcat.R directly via URL or local path:

B. Standard Usage in R Scripts

library(ggplot2)
source("r/theme_wildcat.R")

ggplot(df, aes(x = weight, y = mpg, color = foreign)) +
  geom_point(size = 2.2) +
  scale_color_wildcat() +     # Or scale_color_nu()
  theme_wildcat() +           # Or theme_nu()
  labs(
    title = "Automobile Weight vs. Fuel Efficiency",
    subtitle = "Northwestern branding",
    x = "Vehicle Weight (lbs.)",
    y = "Mileage (mpg)",
    caption = "Source: 1978 Automobile Data"
  )

For continuous fills/colors:

C. Comprehensive Example Script (examples.r)

For matching ggplot2 implementations of all 16 standardized chart types, see r/examples.r. It shows how to apply theme_wildcat(), scale_color_nu(), and scale_fill_nu() across the full benchmark suite.

D. Customizing Colors & Palettes in R

In r/theme_wildcat.R:

  1. Add Custom Colors: Add hex codes to wildcat_colors:
    wildcat_colors <- c(
      ...,
      myblue = "#003366",
      mygold = "#FFC72C"
    )
    
  2. Update Discrete Palette: Modify wildcat_palettes$default with your custom color keys.
  3. Custom Theme Name: To rename the theme function, create an alias:
    theme_mycustom <- theme_wildcat
    scale_color_mycustom <- scale_color_wildcat
    

4. Python Workflow (matplotlib)

A. Downloading & Referencing

Agents can download or import theme_wildcat.py and wildcat.mplstyle:

B. Standard Usage in Python Scripts

import matplotlib.pyplot as plt
from py.theme_wildcat import set_theme, wildcat_colors, labs, legend_top

# 1. Apply theme globally
set_theme()

# 2. Build plot
fig, ax = plt.subplots(figsize=(8.0, 5.0))
for group_name, grp in df.groupby("foreign"):
    ax.scatter(grp["weight"], grp["mpg"], label=group_name, s=28)

# 3. Add ggplot2-style titles & subtitle
labs(
    ax,
    title="Automobile Weight vs. Fuel Efficiency",
    subtitle="Northwestern branding",
    x="Vehicle Weight (lbs.)",
    y="Mileage (mpg)",
    caption="Source: 1978 Automobile Data"
)

# 4. Add top legend aligned to ggplot2 position
legend_top(ax, ncol=2)

plt.savefig("figure.png", dpi=300)

C. Comprehensive Example Script (examples.py)

For matching Matplotlib implementations of all 16 standardized chart types, see py/examples.py. It shows how to use set_theme(), labs(), and legend_top() across the full benchmark suite.

D. Customizing Colors & Palettes in Python

In py/theme_wildcat.py:

  1. Add Custom Colors: Add keys to wildcat_colors:
    wildcat_colors["myblue"] = "#003366"
    wildcat_colors["mygold"] = "#FFC72C"
    
  2. Update Discrete Palette: Modify wildcat_palettes["default"] list.
  3. Custom Theme Name: Create alias functions:
    theme_mycustom = set_theme
    

5. Synchronized Benchmark Chart Types (16 Examples)

The three example files (stata/examples.do, r/examples.r, and py/examples.py) implement the identical 16 publication-grade chart types using the shared benchmark datasets in data/:

  1. Scatter Plot with Linear Fit & 95% CI Ribbon (auto.dta)
  2. Horizontal Bar Chart (auto.dta)
  3. Multi-panel Faceted Plot (auto.dta)
  4. Box Plot across Categories (auto.dta)
  5. Multi-line Time Series (trends.dta)
  6. Kernel Density Distribution (auto.dta)
  7. Cleveland Dot Plot (auto.dta)
  8. Lollipop / Stem Plot (lollipop.dta)
  9. Regression Coefficient / Forest Plot (forest.dta)
  10. Dumbbell / Paired Comparison Plot (dumbbell.dta)
  11. Histogram with Density Overlay (auto.dta)
  12. Bubble Chart with Weighted Markers (auto.dta)
  13. Empirical CDF (ECDF) (auto.dta)
  14. Stacked Area Composition Chart (area.dta)
  15. Uncertainty Fan / Ribbon Chart (ribbon.dta)
  16. Bi-Directional / Tornado Bar Chart (pyramid.dta)

Use these example scripts as templates whenever generating charts in any of the three languages to guarantee exact visual parity.


6. Visual Consistency Guardrails for Agents

When generating plots or modifying themes, maintain these parity rules unless users request to change them specifically:

  1. Aspect Ratio & Canvas Geometry:
    • Standard output canvas is $8.0 \times 5.0$ inches (ratio 1.60).
    • In Python, margins are configured in get_wildcat_rcparams(): left=0.075, right=0.972, bottom=0.177, top=0.810.
  2. Legend Positioning:
    • Standard top legend in R sits at row 236 px ($y = 0.840$ in figure coordinates at $1500 \times 2400\text{ px}$).
    • In Python, always use legend_top(ax) or bbox_to_anchor=(x0, 0.840), bbox_transform=fig.transFigure, loc="center left" to avoid shifting plot axes downward.
  3. Typography & Hierarchy:
    • Font family: Arial (sans-serif).
    • Main title: Bold, charcoal #222222, 14.3 pt, flush left.
    • Subtitle: Regular, muted gray #666666, ~10.8 pt, placed below title.
    • Gridlines: Horizontal only, #EAEAEA. Y-axis line and ticks are hidden; X-axis has subtle #CCCCCC baseline.