Utilities & Helpers

Font management and utility functions

Overview

cpaltemplates provides 7 utility functions for font management, plot operations, and accessibility checking.

Font Management

cpal_font_family()

Get the best available CPAL font for different contexts.

cpal_font_family(
  type = c("plot", "interactive", "table", "print"),
  setup = FALSE
)

Arguments

Argument Description Default
type Context for font usage “plot”
setup Attempt font setup if missing FALSE

Font Selection

The function returns fonts in this priority: 1. Inter - Primary CPAL font (preferred) 2. Roboto - Secondary font 3. sans - System fallback

Examples

# Get font for regular plots
cpal_font_family()
#> [1] "Inter"

# Get font for interactive (ggiraph)
cpal_font_family("interactive")
#> [1] "Inter"

# Get font for tables
cpal_font_family("table")
#> [1] "Inter"

# Get font for print
cpal_font_family("print")
#> [1] "Inter"

# Auto-setup if missing
cpal_font_family(setup = TRUE)

cpal_font_family_fallback()

Returns the system font fallback.

cpal_font_family_fallback()
#> [1] "sans"

get_cpal_font_family()

Legacy wrapper for backward compatibility.

get_cpal_font_family(for_interactive = FALSE, setup_if_missing = TRUE)
Deprecated

Use cpal_font_family() instead. This function is maintained for backward compatibility.

setup_cpal_google_fonts()

Download and register Inter/Roboto fonts from Google Fonts.

setup_cpal_google_fonts(force_refresh = FALSE, verbose = TRUE)

Arguments

Argument Description Default
force_refresh Re-download even if fonts exist FALSE
verbose Print status messages TRUE

What It Does

  1. Downloads Inter and Roboto from Google Fonts
  2. Registers fonts with sysfonts for static plots
  3. Registers fonts with gdtools for interactive plots
  4. Enables showtext for font rendering

Examples

# Standard setup (run once per session)
setup_cpal_google_fonts()
#> Setting up CPAL fonts...
#> ✓ Downloaded Inter from Google Fonts
#> ✓ Downloaded Roboto from Google Fonts
#> ✓ Registered fonts with sysfonts
#> ✓ Enabled showtext
#> Font setup complete!

# Force re-download
setup_cpal_google_fonts(force_refresh = TRUE)

# Quiet mode
setup_cpal_google_fonts(verbose = FALSE)

Plot Utilities

save_cpal_plot()

Save plots with standardized CPAL dimensions.

save_cpal_plot(
  plot,
  filename,
  size = "default",
  dpi = 300,
  bg = "white",
  ...
)

See Themes & Styling for detailed documentation.

check_plot_accessibility()

Analyze a plot for accessibility issues.

check_plot_accessibility(plot, verbose = TRUE)

What It Checks

  1. Text Size - Are labels readable?
  2. Color Contrast - Do colors meet WCAG standards?
  3. Colorblind Safety - Are colors distinguishable?

See Themes & Styling for detailed documentation.

Common Patterns

Session Setup Script

Create a setup script for consistent initialization:

# setup.R - Source at the start of analysis

library(cpaltemplates)
library(ggplot2)
library(dplyr)

# Set up fonts
setup_cpal_google_fonts()

# Set default theme for session
set_theme_cpal()

# Verify setup
message("CPAL environment ready")
message("Font: ", cpal_font_family())

R Profile Integration

Add to .Rprofile for automatic setup:

# .Rprofile
if (interactive()) {
  setHook("rstudio.sessionInit", function(newSession) {
    if (newSession) {
      if (requireNamespace("cpaltemplates", quietly = TRUE)) {
        cpaltemplates::setup_cpal_google_fonts(verbose = FALSE)
      }
    }
  }, action = "append")
}

Project-Level Setup

# _setup.R (sourced by targets or analysis scripts)

# Font setup
cpaltemplates::setup_cpal_google_fonts()

# Set global options
options(
  cpaltemplates.dpi = 300,
  cpaltemplates.size = "slide"
)

Font Troubleshooting

Fonts Not Rendering

# Check if fonts are available
sysfonts::font_families()

# Force setup
setup_cpal_google_fonts(force_refresh = TRUE, verbose = TRUE)

# Verify
cpal_font_family(setup = TRUE)

Interactive Plot Fonts

# Install required packages
install.packages(c("gdtools", "systemfonts"))

# Register fonts for ggiraph
if (requireNamespace("gdtools", quietly = TRUE)) {
  gdtools::register_gfont("Inter")
  gdtools::register_gfont("Roboto")
}

PDF/Print Fonts

# For PDF output, use showtext
library(showtext)
showtext_auto()

# Save with cairo device for better font support
ggsave("plot.pdf", device = cairo_pdf)

Font Fallback

# When fonts aren't available
tryCatch({
  font <- cpal_font_family()
}, error = function(e) {
  font <- cpal_font_family_fallback()  # Returns "sans"
})

Helper Functions Reference

Function Purpose
cpal_font_family() Get appropriate font for context
cpal_font_family_fallback() Get system fallback font
get_cpal_font_family() Legacy font accessor
setup_cpal_google_fonts() Download and register fonts
save_cpal_plot() Save with standard dimensions
add_cpal_logo() Add logo to plots
check_plot_accessibility() Accessibility analysis

Environment Variables

cpaltemplates respects these environment variables:

Variable Purpose
MAPBOX_PUBLIC_TOKEN Mapbox API token for maps
CPAL_FONT_SETUP Skip font setup if “FALSE”
R_CPAL_VERBOSE Control message verbosity 
# Set environment variables
Sys.setenv(MAPBOX_PUBLIC_TOKEN = "pk.xxx...")
Sys.setenv(CPAL_FONT_SETUP = "TRUE")

Next Steps