Skip to contents

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

The `ofce` package is an R package for creating scientific documents following OFCE (Observatoire français des conjonctures économiques) standards. It provides: - ggplot2 themes and color palettes following OFCE/Revue graphical standards - Quarto templates for working papers, blogs, presentations, and websites - French-language formatting utilities - Integration with marquee for advanced text rendering

The package is primarily for French economic research publications, with French as the default language.

## Development Commands

### Building and Testing

    # Install package in development mode
    devtools::load_all()

    # Build documentation
    devtools::document()

    # Build and check package
    devtools::check()

    # Build pkgdown site
    pkgdown::build_site()

    # Install from local source
    devtools::install()

### Common Development Tasks

    # Test a specific function interactively
    devtools::load_all()
    library(tidyverse)
    # Your test code here

    # Run examples from a function
    devtools::run_examples()

    # Check package for CRAN compliance
    devtools::check()

## Architecture

### Core Components

Quarto Templates System (`R/quarto.R`, `inst/extdata/templates/`) - `setup_quarto()`: Installs OFCE Quarto extensions to a project - `setup_wp()`, `setup_blog()`, `setup_graph()`, `setup_pres()`: Initialize specific document types with templates - Templates stored in `inst/extdata/templates/` (blog, graph, presentation, website, workingpaper) - Extensions pulled from `ofce/ofce-quarto-extensions` repository

Theme System (`R/theme_ofce.R`) - `theme_ofce()`: Main ggplot2 theme for OFCE graphics following Revue de l’OFCE standards - `theme_ofce_void()`: Simplified theme for maps and minimal graphics - Supports both marquee (advanced markdown text rendering) and standard ggplot2 text elements - Configurable via global options: `ofce.base_size`, `ofce.base_family`, `ofce.marquee`, `ofce.background_color`

Caption System (`R/ofce_caption.R`) - `ofce_caption()`: Creates standardized captions for ggplot2 graphics with source, note, lecture, champ, code - `ofce_caption_gt()`: Caption system for gt tables - `dernier_point()`: Formats “last known data point” dates in French or English - Supports glue string interpolation and marquee markdown transformations (x → superscript, x → subscript)

Palette System (multiple files) - `R/ofce_palette*.R`: Color palettes (main, sequential, diverging, country-specific) - `R/scale_color_pays.R`: Country-specific color scales - Data stored in `inst/palette.ofce.rda`

Graph Export (`R/graph2xxx.R`) - `graph2png()`, `graph2svg()`, `graph2pptx()`: Export graphics in various formats - Handles ggplot2 and tmap objects - Default size: 18cm width, 4:3 ratio - Uses showtext for proper font rendering at high DPI (default 600)

Formatting Utilities (`R/formate.R`) - `fmt_val()`: Format numbers in French style (comma as decimal, space as thousands separator) - `fmt_pct()`: Format percentages - `fmt_mds()`: Format billions of euros (Milliards d’euros)

Initialization System (`R/init_qmd.R`, `inst/rinit.r`) - `init_qmd()`: Sources project-specific or package `rinit.r` at document start - `pathify()`: Resolves paths from project root (paths starting with `/`) - Default `rinit.r` sets up fonts, themes, knitr options, common libraries, and French locale

### Key Design Patterns

Global Options The package heavily uses R options for configuration: - `ofce.base_size`: Base font size (default 12) - `ofce.base_family`: Font family (default “Open Sans”) - `ofce.marquee`: Enable marquee text rendering (default TRUE) - `ofce.background_color`: Background color (default “transparent”) - `ofce.caption.*`: Caption formatting options (wrap, lang, ofce branding, glue interpolation)

Font System - Uses Open Sans as default font (included in `inst/fonts/`) - Relies on showtext/sysfonts for rendering - systemfonts used to register fonts in rinit.r

Marquee vs Standard Text - When `ofce.marquee = TRUE`: Uses `marquee::element_marquee()` for advanced markdown rendering in ggplot2 - When `ofce.marquee = FALSE`: Falls back to standard `ggplot2::element_text()` - This dual system allows for rich text formatting while maintaining compatibility

French Language Defaults - All user-facing text defaults to French - Date formatting uses French locale - Caption labels: “Source”, “Lecture”, “Note”, “Champ”, “Code”, “Dernier point connu” - Most functions have `lang` parameter for English output

## Important Files

- `DESCRIPTION`: Package metadata, dependencies (requires R >= 4.2, Quarto CLI)
- `inst/rinit.r`: Default initialization script sourced by `init_qmd()`
- `inst/extdata/templates/`: Quarto document templates
- `inst/fonts/`: OpenSans font files
- `_pkgdown.yml`: Documentation website configuration
- `.Rbuildignore`: Files to exclude from package builds

## Common Workflows

### Adding a New Graphical Theme Element

1. Edit `R/theme_ofce.R`
2. Update both marquee and non-marquee versions
3. Test with `devtools::load_all()` and create example plots
4. Document changes and rebuild with `devtools::document()`

### Creating a New Quarto Template

1. Add template files to `inst/extdata/templates/[type]/`
2. Create setup function in `R/quarto.R` (e.g., `setup_[type]()`)
3. Update `setup_quarto()` documentation to mention new format
4. Test installation with `setup_quarto()` in a test directory

### Modifying Color Palettes

1. Edit palette data in `data/` directory
2. Update corresponding `R/ofce_palette*.R` file
3. Regenerate `inst/palette.ofce.rda` if needed
4. Update documentation and examples

## Dependencies

Critical Dependencies - ggplot2 >= 4.0.0: Core graphics system - marquee >= 1.2.0: Advanced text rendering - gt >= 1.1.0: Table formatting - quarto: Document rendering (requires Quarto CLI installed) - showtext/sysfonts: Font rendering

Data Processing - tidyverse >= 2.0.0 (dplyr, tidyr, purrr, stringr) - data.table: High-performance data manipulation

Utility - glue: String interpolation - fs: File system operations - lubridate: Date handling

## Notes

- The package website is hosted at https://ofce.github.io/ofce/
- Documentation includes extensive vignettes for different chart types, Quarto usage, and graphic standards
- This is a specialized package for OFCE institutional use, not intended for CRAN
- Uses CC BY 4.0 license