install logo correctly

R/logo.R

@@ -1,19 +1,19 @@
-#' Title
+#' Plot a jpeg image as a raster
 #'
-#' @param path
-#' @param add
-#' @param upscale
-#'
-#' @return
+#' @param path a character representing the relative or absolute path to the image
+#' @param add a logical, TRUE to add the image to an existing plot, FALSE creates a new plot
+#' @param upscale a logical, TRUE upscales the resolution of the graphic by a factor of 3, FALSE
+#' preserves the resolution
+#' @return a rasterImage
 #' @export
 #' @importFrom jpeg readJPEG
 #' @importFrom graphics rasterImage
 #' @examples
-#' img <- readJPEG(system.file("img","Rlogo.jpg",package="jpeg"))
+#' img <- system.file("img","Civilytics Consulting Logo.jpg",package="civilytics")
+#' plot_jpeg(img)
 plot_jpeg <- function(path, add=FALSE, upscale = TRUE)
 {
-  require('jpeg')
-  jpg = readJPEG(path, native=T) # read the file
+  jpg = readJPEG(path, native = T) # read the file
   res = dim(jpg)[2:1] # get the resolution, [x, y]
   if (upscale){
     res <- res * 3
@@ -26,9 +26,9 @@ plot_jpeg <- function(path, add=FALSE, upscale = TRUE)
 }
 
 
-#' Title
+#' Plot a PNG file as a rasterGrob for inclusion in ggplot2
 #'
-#' @param filename
+#' @param filename a character with file path to a png file
 #'
 #' @return
 #' @export
@@ -36,16 +36,17 @@ plot_jpeg <- function(path, add=FALSE, upscale = TRUE)
 #' @importFrom grid rasterGrob
 #'
 #' @examples
+#'
 get_png <- function(filename) {
   grid::rasterGrob(png::readPNG(filename), interpolate = TRUE)
 }
 
 
-#' Title
+#' Add a logo to a ggplot2 object
 #'
-#' @param plot
-#' @param logo
-#' @param margin_param
+#' @param plot a ggplot2 grob
+#' @param logo a logo grob created by make_logo_grob()
+#' @param margin_param a numeric specifying what margin to add or subtract to align the logo
 #'
 #' @return
 #' @importFrom ggplot2 theme
@@ -73,15 +74,18 @@ add_logo <- function(plot, logo, margin_param = NULL) {
               padding = unit(0.1, "line"))
 }
 
-#' Title
+#' Measure a ggplot2 object caption
 #'
-#' @param gg
+#' @param gg a ggplot object
 #'
-#' @return
+#' @return a numeric value stating the number of lines to be added or subtracted to align a logo with
+#' the caption
 #' @importFrom stringr str_count
 #' @export
 #'
 #' @examples
+#' p1 <- qplot(mpg, wt, data = mtcars)
+#' measure_caption(p1) # Should equal 1 since no caption is required
 measure_caption <- function(gg) {
   if (has_caption(gg)) {
     stringr::str_count(gg$labels$caption, pattern = "\n") + 1
@@ -91,32 +95,43 @@ measure_caption <- function(gg) {
 }
 
 
-#' Title
+#' Test whether a ggplot2 object has a caption
 #'
-#' @param gg
+#' @param gg a gg object from ggplot2
 #'
-#' @return
+#' @return a logical, TRUE if a caption exists and FALSE if it does not
+#' @import ggplot2
 #' @export
 #'
 #' @examples
+#' p1 <- ggplot2::qplot(mpg, wt, data = mtcars)
+#' has_caption(p1) # FALSE
 has_caption <- function(gg) {
   any(names(gg$labels) == "caption")
 }
 
-#' Title
+#' Add a logo to a ggplot2 object
 #'
-#' @param plot_list
-#' @param logo
-#' @param nrow
-#' @param widths
-#' @param margin_param
+#' @param plot_list a list containing ggplot2 objects
+#' @param logo a grob containing the logo created with `make_logo_grob`
+#' @param nrow an integer, default = 1, for the number of rows to align the plots in
+#' @param widths an optional vector the same length as plot_list with the widths for each plot
+#' @param margin_param a number giving the adjustment up or down to help manually align logo and captions
 #'
 #' @return
+#' @note The resulting object needs to be drawn to the screen using grid.draw()
 #' @importFrom gridExtra arrangeGrob
 #' @importFrom ggplot2 theme
+#' @importFrom grid grid.draw
 #' @export
 #'
 #' @examples
+#' library(ggplot2); library(grid)
+#' tmp_plot <- ggplot(mtcars) + aes(x = hp, y = disp) + geom_point() + theme_civilytics()
+#' tmp_logo <- make_logo_grob()
+#' plot_and_logo <- add_logo(tmp_plot, tmp_logo)
+#' grid.draw(plot_and_logo)
+#' dev.off()
 add_logo_ga <- function(plot_list, logo, nrow = 1, widths = NULL, margin_param = NULL) {
   # Change position of logo depending on if plot has a caption
   if (!is.null(margin_param)) {
@@ -146,14 +161,18 @@ add_logo_ga <- function(plot_list, logo, nrow = 1, widths = NULL, margin_param =
 
 #' Get a Civilytics Logo grob
 #'
-#' @return
+#' @return a gg object which contains the logo file stored as a Grob suitable for manipulating in
+#' grid
 #' @export
-#'
+#' @import ggplot2
 #' @examples
+#' logo <- make_logo_grob()
+#' class(logo) # gg
 make_logo_grob <- function() {
   logo_grob <- ggplot(mapping = aes(x = 0:1, y = 1)) +
     theme_void() +
     annotation_custom(get_png(system.file("img", "civilytics_logo.png",
-                                          package="civilytics")), xmin = 0.825, xmax = 1)
+                                          package="civilytics")), xmin= 0.7, xmax = 1)
   logo_grob
 }
+