Publishing Analysis Artifacts

library(qtkit)
library(ggplot2)
library(dplyr)
library(knitr)
library(kableExtra)

Introduction

The {qtkit} package provides several functions to help publish analysis artifacts in a standardized way:

These functions handle common tasks like:

Writing Tables

Basic Table Export

Let’s create and save a simple table using write_kbl():

# Create a basic table
mtcars_table <- mtcars[1:5, 1:4] |>
  kable(format = "html") |>
  kable_styling(bootstrap_options = "striped")

# Save to file
write_kbl(
  kbl_obj = mtcars_table,
  file = "mtcars_table",
  target_dir = "artifacts/",
  device = "png"
)

Customizing Table Output

You can customize the output format and styling:

mtcars_table <- mtcars[1:5, 1:4] |>
  kable(format = "html") |>
  kable_styling(
    bootstrap_options = c("striped", "hover"),
    full_width = FALSE
  ) |>
  row_spec(0, bold = TRUE)

write_kbl(
  kbl_obj = mtcars_table,
  file = "mtcars_styled",
  target_dir = "artifacts/",
  device = "png",
  bs_theme = "flatly"
)

Writing Plots

Basic Plot Export

Save ggplot2 plots with write_gg():

# Create a basic plot
p <- ggplot(mtcars, aes(wt, mpg)) +
  geom_point() +
  theme_minimal()

# Save to file
write_gg(
  gg_obj = p,
  file = "mtcars_plot",
  target_dir = "artifacts/",
  device = "png"
)

Customizing Plot Output

Add custom themes and formatting:

p <- ggplot(mtcars, aes(wt, mpg, color = factor(cyl))) +
  geom_point(size = 3) +
  theme_minimal() +
  labs(
    title = "Car Weight vs Fuel Efficiency",
    x = "Weight (1000 lbs)",
    y = "Miles per Gallon",
    color = "Cylinders"
  )

write_gg(
  gg_obj = p,
  file = "mtcars_plot_styled",
  target_dir = "artifacts/",
  device = "png",
  width = 8,
  height = 6,
  dpi = 300
)

Writing R Objects

Saving Data Objects

Use write_obj() to save R objects for later use:

# Create a filtered dataset
mtcars_subset <- mtcars |>
  filter(cyl == 4) |>
  select(mpg, wt, hp)

# Save to file
write_obj(
  obj = mtcars_subset,
  file = "mtcars_4cyl",
  target_dir = "artifacts/"
)

Reading Saved Artifacts

Tables and plots saved with {qtkit} can be easily restored from the directory where they have been saved (in this case artifacts/). For image formats, you can use the knitr::include_graphics() function, markdown, or HTML:

knitr::include_graphics("artifacts/mtcars_plot.png")
![mtcars_plot](artifacts/mtcars_plot.png)
<img src="artifacts/mtcars_plot.png" alt="mtcars_plot" style="display: block; margin: auto;" />

Objects can be read back using dget():

# Read the saved object
restored_data <- dget("artifacts/mtcars_4cyl")

# Check the restored object
glimpse(restored_data)
#> Rows: 11
#> Columns: 3
#> $ mpg <dbl> 22.8, 24.4, 22.8, 32.4, 30.4, 33.9, 21.5, 27.3, 26.0, 30.4, 21.4
#> $ wt  <dbl> 2.320, 3.190, 3.150, 2.200, 1.615, 1.835, 2.465, 1.935, 2.140, 1.5…
#> $ hp  <dbl> 93, 62, 95, 66, 52, 65, 97, 66, 91, 113, 109

Tip Note that tables and plots need not be saved with the write_kbl() and write_gg() functions to be restored. These objects can be saved and restored using the write_obj() and dget() function as well.

Best Practices

  1. Use consistent naming conventions
  2. Create organized directory structures
  3. Document output formats and locations
  4. Include version control for outputs when appropriate
  5. Validate restored objects match originals

Additional Resources