Skip to content

CLAUDE.md

Latest commit

 

History

History
247 lines (193 loc) · 13.1 KB

CLAUDE.md

File metadata and controls

247 lines (193 loc) · 13.1 KB
Raw

tinyplot - AI Assistant Context

Package Overview

tinyplot is a lightweight extension of base R graphics providing automatic legends, facets, themes, and other enhancements. Zero recursive dependencies — only base R.

  • Main function: tinyplot() (alias: plt())
  • Add layers: tinyplot_add() / plt_add()
  • Themes: tinytheme()
  • Parameters: tpar()

Quick Reference

When working on tinyplot interactively, always use pkgload::load_all() to load the development version — never library(tinyplot). This ensures you're testing your local changes, not an installed copy.

pkgload::load_all()

# Then test interactively, e.g.
plt(Sepal.Length ~ Petal.Length | Species, data = iris)

Repository Structure

  • R/ — Package source. The main entry point is tinyplot.R (~57KB). Plot types live in type_*.R files. Other key files include legend.R, facet.R, by_aesthetics.R, tinytheme.R, tpar.R, and environment.R. Input validation helpers follow the sanitize_*.R naming convention. Utility functions are in utils.R.
  • inst/tinytest/ — Test suite (tinytest + tinysnapshot). Snapshot SVGs are in _tinysnapshot/.
  • man/ — roxygen2-generated .Rd files.
  • vignettes/ — Package vignettes (qmd format).
  • SCRATCH/ — Developer scratch files and experiments (not part of the package).

Code Style & Conventions

Zero Dependency Requirement

tinyplot has zero recursive dependencies — it imports only base R packages (graphics, grDevices, stats, tools, utils). All contributions must preserve this. Do not add new package dependencies under Imports or Depends.

Assignment & Syntax

# Use = not <-
x = 5

# Use function() not \() — package requires R >= 4.0.0 compatibility
fn = function(x) x^2

# Prefer [[ over $ for element access (no partial matching, works with variables)
legend_args[["title"]]
settings[["datapoints"]]
# NOT: legend_args$title, settings$datapoints

No Pipes in Package Code

The package targets R >= 4.0.0, so the base pipe |> (introduced in 4.1) is not available. Use intermediate variables or nested calls instead.

Line Length

Wrap at ~80 characters. Break long function calls across lines.

Architecture & Key Patterns

Execution Flow

The main pipeline in tinyplot.default() follows this sequence:

  1. Save par state and the call (for tinyplot_add() replay)
  2. Build a settings environment with all inputs
  3. Sanitize inputs: type → axes → labels → facets → datapoints
  4. Run the type's data function (type_data(settings)) to transform data
  5. Handle flipping, bubble sizing, axis limits
  6. Compute group aesthetics (colours, pch, lty, etc.)
  7. Prepare legends
  8. Draw the facet grid (if any)
  9. Nested drawing loop: outer loop over facets, inner loop over by groups — each iteration calls the type's draw function with per-group data
  10. Save end par state for layer recall

Type System

Each plot type is a tinyplot_type S3 object created by a type_*() constructor:

type_boxplot = function(range = 1.5, ...) {
  out = list(
    draw = draw_boxplot(range = range, ...),  # closure: does actual plotting per group
    data = data_boxplot(...),                  # closure: preprocesses data, injects into settings
    name = "boxplot"                           # string identifier
  )
  class(out) = "tinyplot_type"
  return(out)
}
  • draw function signature: function(iby, ix, iy, ipch, ilty, icol, ibg, ...)
    • Called once per group (iby = group index)
    • Receives per-group subsetted data
  • data function signature: function(settings, ...)
    • Receives the settings environment
    • Reads from settings via env2env(settings, environment(), keys)
    • Writes back via env2env(environment(), settings, keys)
    • Can modify datapoints, xlabs, col, bg, by, facet, group_offsets, legend args, etc.

Settings Environment

Individual tinyplot() calls store plot state in a temporary settings environment. Type-specific data functions read/write to this environment using env2env(). This avoids copying large objects and allows types to customize behaviour.

Package-Level State (.tinyplot_env)

Managed via get_environment_variable() / set_environment_variable() in environment.R:

  • .last_call — last tinyplot call (used by tinyplot_add())
  • .saved_par_before / .saved_par_after / .saved_par_first — par state for layer restoration
  • .tpar_hooks — theme hooks
  • .group_offsets — dodge offsets for layering (used by jitter-on-boxplot etc.)

recordGraphics() for Resize Handling

Coordinate-dependent calculations (especially legends) must be wrapped in recordGraphics() so they replay correctly on device resize:

recordGraphics(
  tinylegend(legend_env),
  list = list(legend_env = legend_env),
  env = getNamespace("tinyplot")
)

Theme System

Themes use before.plot.new hooks. Legend code must preserve/restore hooks:

oldhook = getHook("before.plot.new")
setHook("before.plot.new", function() par(new = TRUE), action = "append")
plot.new()
setHook("before.plot.new", oldhook, action = "replace")

Legend Positioning

  • Inner positions: "right", "topleft", etc.
  • Outer positions (with !): "right!", "bottom!", etc.
  • Outer legends adjust plot margins via par(oma=...) and par(mar=...)

Group Offsets / Dodge

When multiple groups share the same x-position (boxplot, violin, etc.), offsets are computed in the type's data function and stored as group_offsets + offsets_axis. These are saved to .tinyplot_env so that tinyplot_add() layers (e.g., jitter) can align correctly.

Testing & CI

Tests use tinytest + tinysnapshot. Snapshot tests produce SVG output with Liberation fonts and are meant to run on Linux (helpers.R sets tinysnapshot_os = "Linux"); they only run when the environment variable NOT_CRAN is set to the lowercase string "true". Non-snapshot tests (logical assertions, error checks) run anywhere.

On Linux you can generally just run the suite directly and expect it to match CI. Snapshots are byte-compared against amd64 reference images, so the usual things that trip people up are (a) not being on Linux/amd64, and (b) a stale render toolchain — e.g. distro/PPM package binaries built against an older R after a minor bump, which make svglite/systemfonts/textshaping/rsvg/magick error or drift. A handful of pure text/glyph-metric diffs (titles, themed labels, plotmath) almost always means one of those, not a code regression; a larger or structural set of failures is the real thing. CI is the final arbiter.

Running Tests

Pick the path that fits your setup:

Native Linux (amd64) — fastest. make testall runs directly against your R install and should match CI. Snapshots only run with NOT_CRAN=true set (lowercase). If the render stack errors ("Graphics API version mismatch") or snapshots drift, it's the stale-toolchain gotcha above — reinstall svglite, magick, rsvg, systemfonts, textshaping from source.

VS Code devcontainer (any OS). Open the repo in VS Code → Command Palette → "Dev Containers: Reopen in Container" (deps install automatically), then make testall. Also works via GitHub Codespaces.

Terminal container runner (any OS with Docker/Podman/Finch/nerdctl). No editor required:

  • make testall-docker — full suite in a Linux container at your native architecture.
  • make testall-ci — same, forced to amd64 (--platform linux/amd64). On Apple Silicon this is the CI-faithful run: arm64-native rendering differs subtly from the amd64 reference SVGs, so a native-arch run shows a couple of spurious text-snapshot diffs. It's emulated (slower), so iterate with testall-docker and confirm with testall-ci before pushing.
make testall            # native Linux host
make testall-docker     # container, native arch
make testall-ci         # container, amd64 (CI-faithful; needed on Apple Silicon)
make testone testfile="inst/tinytest/test-legend.R"       # single file, native
.devcontainer/run-tests.sh inst/tinytest/test-legend.R    # single file, container

# Via R (Linux, NOT_CRAN=true)
tinytest::run_test_dir("inst/tinytest")
tinytest::run_test_file("inst/tinytest/test-legend.R")

Continuous Integration

PRs against main automatically trigger GitHub Actions CI, which runs R CMD check (including the full test suite) on Ubuntu with both R-release and R-devel. Snapshot tests are included in this CI run, so even if you can't run them locally, CI will catch any regressions.

CRAN Submissions

The test suite (snapshot SVGs in particular) adds significant size to the installed package. Tests are only intended to run locally and on CI — not on CRAN.

Pre-submission checklist:

  1. Create a new branch cran_v<x.x.x> from main
  2. Verify version is updated and aligned in both DESCRIPTION and NEWS.md
  3. Verify Date field in DESCRIPTION matches the submission date
  4. Update cran-comments.md with new version and release type
  5. Open a PR from the branch to main
  6. Verify CI passes on the PR
  7. Run reverse dependency checks: push a revdep-v<x.x.x> branch to trigger the revdep workflow
  8. Uncomment the inst/tinytest/ line in .Rbuildignore to exclude tests from tarball
  9. Run devtools::check_win_devel() and wait for results
  10. Run R CMD check --as-cran locally
  11. Fix any issues / notes and update cran-comments.md as necessary
  12. Submit to CRAN

Post-acceptance:

  1. Re-comment the inst/tinytest/ line in .Rbuildignore and push to PR so CI continues to pick up tests
  2. Merge the PR to main
  3. Create a new GitHub release tagged v<x.x.x>

Manual Testing

Some features require manual testing, particularly:

  • Window resize behaviour (legends, facets, layers should stay aligned)
  • Positron IDE compatibility
  • Interactive device behaviour

Contributing

All contributions should go through a pull request against main.

  • Always work on a fresh branch. Every PR-based contribution must start on a new branch created from the latest origin/main (git fetch && git switch --no-track -c <branch> origin/main, then git push -u origin <branch> on first push). The --no-track matters: without it the branch tracks origin/main, so a plain git push or an IDE "sync" pushes straight to main. Never commit directly to main, and never reuse or stack work onto an existing feature branch. Overriding this requires explicit opt-in from the maintainer.

Development Workflow

Makefile Commands

make help        # Show all available commands
make document    # Generate documentation (devtools::document)
make check       # Full R CMD check
make install     # Install package locally
make website     # Build documentation website (altdoc)

Adding a New Plot Type

Where possible, reuse existing draw_*() and data_*() functions rather than writing new ones from scratch. Many types are thin wrappers that combine existing building blocks with custom data transformations. For example:

  • type_lm, type_glm, and type_loess all use draw_ribbon() — they only differ in their data_*() functions
  • type_barplot and type_histogram both use draw_rect()
  • type_jitter and type_pointrange both use draw_points()
  • type_spline and type_summary both use draw_lines()
  • type_errorbar reuses data_pointrange() entirely
  • type_area has no draw function at all — its data function sets type = "ribbon" to delegate drawing

Steps:

  1. Create R/type_<name>.R with the type_<name>() constructor, draw_<name>(), and optionally data_<name>()
  2. Register the type in R/sanitize_type.R: add the string name to the known_types vector and a corresponding entry in the switch statement that maps it to the constructor
  3. Add @export tag to the constructor
  4. Run make document to update NAMESPACE
  5. Add tests in inst/tinytest/test-type_<name>.R
  6. Add snapshot SVGs by running tests on Linux (devcontainer)
  7. Add the new page to the website navigation in altdoc/quarto_website.yml

Important: Step 7 applies to any new exported function or page, not just plot types. Whenever you add or rename an exported function that gets its own .Rd page, add it to altdoc/quarto_website.yml under the appropriate section.

Modifying Legend Behaviour

Type-specific legend customizations should go in the type's data function by modifying settings$legend_args:

settings$legend_args[["pch"]] = settings$legend_args[["pch"]] %||% 22
settings$legend_args[["pt.cex"]] = settings$legend_args[["pt.cex"]] %||% 3.5

Common Pitfalls

  • Legend misalignment on resize: Ensure coordinate-dependent calculations are inside recordGraphics(). See PRs #438, #540, #541.
  • Layer alignment with grouped types: When adding jitter/points on top of boxplot/violin, the layer needs access to group_offsets from .tinyplot_env. See PR #561.
  • Theme hook corruption: Always save and restore before.plot.new hooks when calling plot.new() in legend code.
  • R 4.0.0 compat: No |> pipe, no \() lambda.

Links