fix: address review round 3 for #7

Reviewed-on: #9

NAMESPACE

@@ -42,6 +42,7 @@ export(safe_ratio)
 export(scale_color_civilytics)
 export(scale_fill_civilytics)
 export(simpleCap)
+export(stamp_logo_png)
 export(star_subs)
 export(theme_civilytics)
 export(theme_civilytics_dark)
@@ -61,8 +62,12 @@ importFrom(ggplot2,annotation_custom)
 importFrom(ggplot2,ggplot)
 importFrom(ggplot2,theme)
 importFrom(ggplot2,theme_void)
+importFrom(grDevices,dev.off)
+importFrom(grDevices,png)
 importFrom(graphics,rasterImage)
 importFrom(grid,grid.draw)
+importFrom(grid,grid.newpage)
+importFrom(grid,grid.raster)
 importFrom(grid,rasterGrob)
 importFrom(gridExtra,arrangeGrob)
 importFrom(jpeg,readJPEG)

R/db.R

@@ -111,7 +111,9 @@ nvals <- function(x){
 #' simpleCap(my_string)
 simpleCap <- function(x) {
   stopifnot(class(x) == "character")
-  s <- strsplit(x, " ")[[1]]
+  sapply(x, function(word) {
-  paste(toupper(substring(s, 1,1)), substring(s, 2),
+    s <- strsplit(word, " ")[[1]]
+    paste(toupper(substring(s, 1, 1)), substring(s, 2),
           sep = "", collapse = " ")
+  })
 }

R/logo.R

@@ -361,3 +361,92 @@ civilytics_logo <- function(plot,
            position = position)
 }
 
+
+#' Stamp the Civilytics logo onto a saved raster (PNG) image
+#'
+#' The raster analogue of [civilytics_logo()] for outputs that are already
+#' rendered to a file rather than held as a ggplot/grob — e.g. a `flextable`
+#' exported to PNG, or any `grDevices::png()` / `ragg::agg_png()` output.
+#' Resolves the *same* brand asset that [make_logo_grob()] uses, so file-based
+#' tables stay visually consistent with logo-branded plots, and composites it
+#' into a corner of the image. Pure base-graphics + grid + png — no new
+#' package dependencies.
+#'
+#' @param path Character. Path to the PNG to stamp. The file is overwritten
+#'   in place at its original pixel dimensions.
+#' @param type Character. `"wordmark"` (default) or `"mark"`. As in
+#'   [make_logo_grob()].
+#' @param variant Character. `"light"` (default, dark logo for light
+#'   backgrounds) or `"dark"` (reverse logo for dark backgrounds).
+#' @param position Character. Corner placement: `"bottom-right"` (default),
+#'   `"bottom-left"`, `"top-right"`, or `"top-left"`.
+#' @param width_frac Numeric. Logo width as a fraction of the image width
+#'   (default `0.15`). Height follows from the logo's aspect ratio.
+#' @param margin_frac Numeric. Padding from the edges as a fraction of the
+#'   image width (default `0.02`).
+#'
+#' @return `path`, invisibly.
+#' @export
+#' @importFrom png readPNG
+#' @importFrom grid grid.newpage grid.raster
+#' @importFrom grDevices png dev.off
+#' @examples
+#' \dontrun{
+#' # Brand a table exported to PNG so it matches civilytics_logo()-branded plots
+#' ragg::agg_png("table.png", width = 8, height = 4, units = "in", res = 200)
+#' plot(flextable::flextable(head(mtcars)))
+#' dev.off()
+#' stamp_logo_png("table.png")                         # wordmark, bottom-right
+#' stamp_logo_png("table.png", type = "mark", position = "bottom-left")
+#' }
+stamp_logo_png <- function(path,
+                           type = c("wordmark", "mark"),
+                           variant = c("light", "dark"),
+                           position = c("bottom-right", "bottom-left",
+                                        "top-right", "top-left"),
+                           width_frac = 0.15,
+                           margin_frac = 0.02) {
+  type     <- match.arg(type)
+  variant  <- match.arg(variant)
+  position <- match.arg(position)
+  stopifnot(file.exists(path))
+
+  # Same asset selection as make_logo_grob() so files match branded plots.
+  img_file <- switch(
+    paste(type, variant, sep = "_"),
+    wordmark_light = "civilytics-wordmark.png",
+    wordmark_dark  = "civilytics-wordmark-reverse.png",
+    mark_light     = "civilytics-mark.png",
+    mark_dark      = "civilytics-mark-reverse.png"
+  )
+  logo_path <- system.file("img", img_file, package = "civilytics")
+  if (!nzchar(logo_path)) {
+    stop("Civilytics logo asset not found in the 'civilytics' package: ", img_file)
+  }
+
+  base_img <- png::readPNG(path)        # height x width x channels, values in [0, 1]
+  logo_img <- png::readPNG(logo_path)
+  h <- dim(base_img)[1]
+  w <- dim(base_img)[2]
+  aspect <- dim(logo_img)[1] / dim(logo_img)[2]   # logo height / width
+
+  # Sizes/margins are expressed relative to image WIDTH, then converted to the
+  # device's npc units (which scale with the viewport's own width and height).
+  lw <- width_frac
+  lh <- width_frac * aspect * (w / h)
+  mx <- margin_frac
+  my <- margin_frac * (w / h)
+
+  x <- if (grepl("right", position)) 1 - mx else mx
+  y <- if (grepl("top",   position)) 1 - my else my
+  just <- c(if (grepl("right", position)) "right" else "left",
+            if (grepl("top",   position)) "top"   else "bottom")
+
+  grDevices::png(path, width = w, height = h, units = "px")
+  on.exit(grDevices::dev.off(), add = TRUE)
+  grid::grid.newpage()
+  grid::grid.raster(base_img, width = 1, height = 1, interpolate = FALSE)
+  grid::grid.raster(logo_img, x = x, y = y, width = lw, height = lh,
+                    just = just, interpolate = TRUE)
+  invisible(path)
+}

R/theme.R

@@ -36,10 +36,9 @@
 #'   to [civilytics_colors]`["paper_2"]` (`#F2EDE4`).
 #' @param grid Character. Which major gridlines to draw: `"y"` (default,
 #'   horizontal only), `"x"` (vertical only), `"both"`, or `"none"`.
-#' @param paper_bg Logical. If `TRUE` (default), fill the plot and panel
+#' @param paper_bg Logical. If `FALSE` (default), the plot and panel
-#'   backgrounds with the warm `paper` color. Set to `FALSE` for a
+#'   backgrounds are transparent (`fill = NA`). Set to `TRUE` to fill them
-#'   transparent background (useful for slides or overlay on colored
+#'   with the warm `paper` color (the Civilytics cream canvas).
-#'   surfaces).
 #'
 #' @section Font size hierarchy:
 #' All text sizes are derived from `font_size` using relative scale factors.
@@ -68,26 +67,29 @@
 #' \dontrun{
 #' library(ggplot2)
 #'
-#' # Default editorial theme
+#' # Transparent background (default) — composites cleanly onto any surface
 #' ggplot(mpg, aes(displ, hwy)) +
 #'   geom_point() +
 #'   theme_civilytics()
 #'
+#' # Warm paper canvas (opt-in)
+#' ggplot(mpg, aes(displ, hwy)) +
+#'   geom_point() +
+#'   theme_civilytics(paper_bg = TRUE)
+#'
 #' # With both gridlines and brand colors
 #' ggplot(mpg, aes(displ, hwy, colour = class)) +
 #'   geom_point() +
 #'   scale_color_civilytics() +
 #'   theme_civilytics(grid = "both")
 #'
-#' # Transparent background for embedding
-#' ggplot(mpg, aes(displ, hwy)) +
-#'   geom_point() +
-#'   theme_civilytics(paper_bg = FALSE)
-#'
 #' # Larger text for poster or display
 #' ggplot(mpg, aes(displ, hwy)) +
 #'   geom_point() +
 #'   theme_civilytics(font_size = 18)
+#'
+#' # Note: for fully-transparent PNGs, also set a transparent device
+#' # background (e.g. `ggsave("plot.png", bg = NA)`).
 #' }
 theme_civilytics <- function(
     font_size    = 14,
@@ -102,7 +104,7 @@ theme_civilytics <- function(
     accent       = unname(civilytics_colors["ember_600"]),
     strip_color  = unname(civilytics_colors["paper_2"]),
     grid         = c("y", "x", "both", "none"),
-    paper_bg     = TRUE) {
+    paper_bg     = FALSE) {
 
   grid <- match.arg(grid)
   half_line  <- font_size / 2

R/utils.R

@@ -31,7 +31,7 @@ safe_max <- function(x) {
 #' pretty_per(0.2, ndigit = 1)
 #' pretty_per(c(0.2, 0.332423, 0.4, 0.342342), ndigit = 2)
 pretty_per <- function(x, ndigit = 1) {
-  if (any(x >= 100) & !all(is.na(x))) {
+  if (any(x >= 100) && !all(is.na(x))) {
     message("Values over 100 found, did you mean to use proportions?")
   }
   x <- format(round(x, digits = ndigit + 2) * 100, nsmall = ndigit)
@@ -283,7 +283,7 @@ get_stabbr <- function(fips) {
   fips_codes <- fips_codes[!duplicated(fips_codes),]
   if (length(fips) != 1) {
     out <- rep(NA, length(fips))
-    for (i in length(fips)) {
+    for (i in seq_along(fips)) {
       out[i] <- fips_codes[fips_codes$state_code == fips, 1]
 
     }
@@ -375,7 +375,7 @@ random_round <- function(x) {
   add = rep(as.integer(0),length(r))
   add[r>test] <- as.integer(1)
   value = v + add
-  ifelse(is.na(value) | value<0, 0, value)
+  value <- ifelse(is.na(value) | value < 0, 0, value)
   return(value)
 }
 

man/stamp_logo_png.Rd

@@ -0,0 +1,56 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/logo.R
+\name{stamp_logo_png}
+\alias{stamp_logo_png}
+\title{Stamp the Civilytics logo onto a saved raster (PNG) image}
+\usage{
+stamp_logo_png(
+  path,
+  type = c("wordmark", "mark"),
+  variant = c("light", "dark"),
+  position = c("bottom-right", "bottom-left", "top-right", "top-left"),
+  width_frac = 0.15,
+  margin_frac = 0.02
+)
+}
+\arguments{
+\item{path}{Character. Path to the PNG to stamp. The file is overwritten
+in place at its original pixel dimensions.}
+
+\item{type}{Character. `"wordmark"` (default) or `"mark"`. As in
+[make_logo_grob()].}
+
+\item{variant}{Character. `"light"` (default, dark logo for light
+backgrounds) or `"dark"` (reverse logo for dark backgrounds).}
+
+\item{position}{Character. Corner placement: `"bottom-right"` (default),
+`"bottom-left"`, `"top-right"`, or `"top-left"`.}
+
+\item{width_frac}{Numeric. Logo width as a fraction of the image width
+(default `0.15`). Height follows from the logo's aspect ratio.}
+
+\item{margin_frac}{Numeric. Padding from the edges as a fraction of the
+image width (default `0.02`).}
+}
+\value{
+`path`, invisibly.
+}
+\description{
+The raster analogue of [civilytics_logo()] for outputs that are already
+rendered to a file rather than held as a ggplot/grob — e.g. a `flextable`
+exported to PNG, or any `grDevices::png()` / `ragg::agg_png()` output.
+Resolves the *same* brand asset that [make_logo_grob()] uses, so file-based
+tables stay visually consistent with logo-branded plots, and composites it
+into a corner of the image. Pure base-graphics + grid + png — no new
+package dependencies.
+}
+\examples{
+\dontrun{
+# Brand a table exported to PNG so it matches civilytics_logo()-branded plots
+ragg::agg_png("table.png", width = 8, height = 4, units = "in", res = 200)
+plot(flextable::flextable(head(mtcars)))
+dev.off()
+stamp_logo_png("table.png")                         # wordmark, bottom-right
+stamp_logo_png("table.png", type = "mark", position = "bottom-left")
+}
+}

tests/testthat/test_logo.R

@@ -0,0 +1,30 @@
+test_that("stamp_logo_png preserves image dimensions and returns the path invisibly", {
+  p <- tempfile(fileext = ".png")
+  on.exit(unlink(p), add = TRUE)
+  grDevices::png(p, width = 600, height = 240); plot(1:5); grDevices::dev.off()
+  in_dim <- dim(png::readPNG(p))[1:2]
+
+  expect_invisible(out <- stamp_logo_png(p))
+  expect_identical(out, p)
+  expect_identical(dim(png::readPNG(p))[1:2], in_dim)  # overwritten at same size
+})
+
+test_that("stamp_logo_png runs for every type/variant/position combination", {
+  p <- tempfile(fileext = ".png")
+  on.exit(unlink(p), add = TRUE)
+  grDevices::png(p, width = 500, height = 200); plot(1:5); grDevices::dev.off()
+
+  for (ty in c("wordmark", "mark")) {
+    for (va in c("light", "dark")) {
+      for (pos in c("bottom-right", "bottom-left", "top-right", "top-left")) {
+        expect_no_error(stamp_logo_png(p, type = ty, variant = va, position = pos))
+      }
+    }
+  }
+})
+
+test_that("stamp_logo_png validates its inputs", {
+  expect_error(stamp_logo_png(tempfile(fileext = ".png")))  # file does not exist
+  # invalid type is rejected by match.arg() before the file is touched
+  expect_error(stamp_logo_png(tempfile(fileext = ".png"), type = "banner"))
+})

tests/testthat/test_theme.R

@@ -133,9 +133,17 @@ test_that("theme_civilytics uses brand ink color for text", {
   expect_equal(th$text$colour, unname(civilytics_colors["ink"]))
 })
 
-test_that("theme_civilytics uses brand paper color for plot background", {
+test_that("theme_civilytics has transparent background by default", {
   th <- theme_civilytics()
+  expect_true(is.na(th$plot.background$fill))
+  expect_true(is.na(th$panel.background$fill))
+  expect_null(th$legend.background$fill)
+})
+
+test_that("theme_civilytics paper_bg=TRUE opt-in fills with cream", {
+  th <- theme_civilytics(paper_bg = TRUE)
   expect_equal(th$plot.background$fill, unname(civilytics_colors["paper"]))
+  expect_equal(th$panel.background$fill, unname(civilytics_colors["paper"]))
 })
 
 test_that("theme_civilytics uses paper_2 for strip background by default", {