Skip to contents

Create a Figure Specification

Source: R/spec_init.R
create_figure.Rd

Create and initialize a TFL specification for embedding a figure. Accepts either a file path to an existing image or a ggplot2 object that is rendered automatically to a temporary file (format chosen by the figureDevice option, default "cairo" — a paths-only, MS Word-safe SVG produced by Cairo; see Details for the fallback chain).

Usage

create_figure(plot_or_path, dpi = 300L)

Arguments

plot_or_path

One of:

  • A character string — path to an existing, readable image file (.png, .jpeg/.jpg, or .svg).

  • A ggplot2 object (class "gg" or "ggplot") — the plot is rendered to a temporary file (ggplot2::ggsave() for raster/svg devices, Cairo::CairoSVG() for the default "cairo"). Use dpi and package options (figureWidth, figureHeight, figureDevice) to control output dimensions and format. Rendered size is driven by figureWidth/figureHeight (NOT by ggplot's own saved size): set both or accept the 6x4in default.

dpi

Integer. Resolution (dots per inch) when plot_or_path is a ggplot2 object. Ignored for file paths. Default: 300.

Value

A TFL_spec object with docType = "Figure".

Details

When a ggplot2 object is passed:

  1. The plot is rendered to a temporary file in tempdir(): with the default figureDevice = "cairo" via Cairo::CairoSVG(onepass = TRUE) (text becomes vector paths — MS Word cannot corrupt it); raster and "svg" devices go through ggplot2::ggsave().

  2. The temporary file path is stored in spec$.metadata$filePath.

  3. save_report() copies the file (prefixed with dataRef) into metaPath, where the C++ renderer reads it. Until then the asset lives only in tempdir() — replay of a saved spec requires the meta folder to be intact.

  4. The temporary file persists for the duration of the R session.

Device availability. The requested figureDevice is resolved through a fallback chain "cairo" -> "svg" -> "png": if the backing package (Cairo or svglite) is unavailable, the next device is used with a once-per-session warning, so figure production never dies on a missing suggested package.

The C++ renderer natively supports .png, .jpeg/.jpg, and .svg formats. Word fidelity: svglite text-SVG is reflowed by MS Word (font substitution, text-anchor and px-scaling bugs that LibreOffice does not show); this is why the default device exports a cairo paths-only SVG. Figures embedded as paths are not text-editable in Word — a deliberate determinism trade for clinical deliverables.

See also

create_table(), create_text(), set_document()

Examples

if (FALSE) { # \dontrun{
## From an existing image file (write your own PNG first, e.g.:
##   png("plot.png", width = 640, height = 480); plot(1:10); dev.off())
spec <- create_figure("plot.png")

## From a ggplot2 object
library(ggplot2)
p <- ggplot(mtcars, aes(x = wt, y = mpg)) + geom_point()
spec <- create_figure(p, dpi = 150)

## Control figure defaults via options (both dims, or accept 6x4in default)
tfl_set_options(figureWidth = "8in", figureHeight = "5in", figureDevice = "png")
spec <- create_figure(p)
tfl_reset_options()

## Default device: cairo paths-only SVG (MS Word-safe vector)
spec <- create_figure(p)          # figureDevice = "cairo"
## Force text-SVG (renders wrong in Word; warns once) or raster:
## tfl_set_options(figureDevice = "svg")
## tfl_set_options(figureDevice = "jpeg")

## Full pipeline
spec <- create_figure(p) |>
  add_title("Weight vs MPG") |>
  add_footnote("Source: Motor Trend, 1974.")
write_doc(create_report(spec), "fig01", outDir = tempdir(),
          metaPath = tempdir(), verbose = FALSE)
} # }