How davidgohel/ggiraph works
Project Type and Purpose
• {ggiraph} is an R package that extends ggplot2 and implements an htmlwidget to render interactive SVG graphics in R, R Markdown and Shiny.
• It provides R functions (e.g., geom_point_interactive(), girafe()) that generate SVG markup with embedded tooltip, onclick and data_id attributes, and leverages C++ for SVG generation performance and JavaScript for client‑side interaction.
File‑Structure Analysis
• R/ – R source code defining exported functions, ggproto extensions, roxygen comments, RcppExports.R.
• src/ – C++ implementation: dsvg device, geometry handling, tinyxml2 XML writer. Build scripts (Makevars*) compile these into a shared library.
• srcjs/ – Raw JavaScript modules for interaction primitives: hover, tooltip, selection, zoom.
• inst/htmlwidgets/ – Packaged htmlwidget artifacts: girafe.js, girafe.yaml, third‑party libs (d3-bundle, save-svg-as-png, etc.).
• man/ – Rd documentation files, figures.
• examples/, inst/examples/, vignettes/ – Usage demos (R scripts, Shiny apps, R Markdown).
• tests/, inst/tinytest/ – Unit and visual tests.
• tools/ – Build helpers (packagejs Webpack config bundling JS/CSS, tinyxml2 patches).
• .github/workflows/ – CI: R‑CMD‑check, pkgdown site, rhub, coverage.
Key Insights from README
• Under the hood: an htmlwidget + ggplot2 extension.
• Interactive aesthetics (tooltip, onclick, data_id) augment ggplot layers; girafe() wraps a ggplot object into an HTML widget.
• Shiny integration: widget exposes selection events to the server via reactive values.
Main Components (
a. User/Client
• R console, R Markdown HTML output, or Shiny app running in a browser.
b. R Session
• Loads {ggiraph}, builds ggplot object with interactive geoms.
• Calls girafe() to export an htmlwidget.
c. C++ Backend (Rcpp)
• RcppExports layer → calls C++ functions in src/.
• dsvg_dev.cpp generates SVG + custom attributes via tinyxml2.
d. htmlwidget Layer
• Wraps generated SVG into an HTML document.
• Uses metadata from inst/htmlwidgets/girafe.yaml to link JS & CSS.
e. JavaScript Runtime
• Bundled JS in inst/htmlwidgets/lib + transpiled srcjs modules.
• Handles mouse events, tooltips, selections, zoom, onclick actions.
f. Browser
• Renders SVG and UI controls (toolbar).
• In Shiny: widget uses Shiny’s message protocol to send selection events back.
g. Shiny Server (optional)
• Receives input from widget, triggers reactive R code, possibly re‑rendering the widget.
Interactions and Data Flows
• R function → C++ → SVG markup → htmlwidget → HTML+JS → Browser
(render)
• Browser events (hover, click, selection) → JavaScript handlers → Shiny (via WebSocket) or direct JS callbacks.
(user interaction)
• In Shiny mode: UI input rebounds to R server → triggers reactivity → widget update.
Architectural Patterns and Design Principles
• Layered architecture: R API → native library → widget wrapper → client runtime.
• Extension pattern: builds on ggplot2’s ggproto system, injecting interactivity at the layer level.
• Separation of concerns: R for API, C++ for high‑performance SVG writing, JS for client interactions.
• Modular JS: custom modules (srcjs) bundled via Webpack (tools/packagejs).
Technologies and Frameworks
• R, ggplot2, htmlwidgets
• C++ (Rcpp) and tinyxml2
• JavaScript, D3.js, Webpack for bundling
• Shiny for server‑side reactivity
• Testing: tinytest, CI with GitHub Actions, codecov