Description
Creating Flexible, Reproducible 'PDF' Reports.
Description
A tool which allows users the ability to intuitively create flexible, reproducible portable document format reports comprised of aesthetically pleasing tables, images, plots and/or text.
README.md
grobblR
The grobblR package allows R users the ability to intuitively create flexible, reproducible PDF reports comprised of aesthetically pleasing tables, images, plots and/or text. This is done by implementing grobs from the grid
and gridExtra
packages.
Within grobblR, the objects able to be converted to a grob are:
- Data frames / matrices
- Or a vector of values
ggplot2
objects- A file path or a URL to a .png image
- Character strings
- Empty space (represented with
NA
)
Example reports created by grobblR.
Installation
You can install the latest version on CRAN with
install.packages("grobblR")
Grob Layout
- We decided on a Shiny-like bootstrap method to arrange grobs, which would incorporate nested grob-rows (a row combining one or several grobs) and grob-columns (a column combining one or several grobs) within an overall layout of grobs (which we will call a grob-layout).
- The main grob-layout function evaluates the overall dimensions of the page you desire, and then distributes heights and widths to the grobs that will make up the page, based on proportions and the amount of grob-rows (
grob_row()
) and grob-columns (grob_col()
) within the overall grob-layout (grob_layout()
). - For example, if we wanted to do a simple
2 x 2
grid system on a100mm x 100mm
(millimeters is the default unit in grobblR) page, we would simply write:
library(grobblR)
grob_layout(
grob_row(grob_col(1), grob_col(2)),
grob_row(grob_col(3), grob_col(4)),
height = 100,
width = 100
) %>%
view_grob()
- The
grob_row()
’s tell thegrob_layout()
that the user wants two rows on the outermost layer, and since there are twogrob_col()
’s within each of thegrob_row()
’s, the result is a2 x 2
grid. - But the result doesn’t have to be a nice
2 x 2
grid - we could have a layout where the first row has two columns and the second has one:
grob_layout(
grob_row(grob_col(1), grob_col(2)),
grob_row(grob_col(3)),
height = 100,
width = 100
) %>%
view_grob()
- Run
vignette("grob_layout")
for more information ongrob_layout()
.
Nested Rows and Columns
- One of the ways that makes grobblR truly flexible is the ability to create “nested” rows and columns - where we can insert grob-rows into grob-columns, and vice-versa.
- This is made possible by incorporating the active classes within the R6 package.
- The below grob-layout has a second grob-column in the second grob-row which contains two grob-rows within it:
grob_layout(
grob_row(
border = TRUE,
grob_col(border = TRUE, 1),
grob_col(border = TRUE, 2)
),
grob_row(
border = TRUE,
grob_col(border = TRUE, 3),
grob_col(
border = TRUE,
grob_row(border = TRUE, grob_col(border = TRUE, 4)),
grob_row(border = TRUE, grob_col(border = TRUE, 5))
)
),
height = 100,
width = 100
) %>%
view_grob()
Size Control
- One way to control heights and widths of the grobs is by tweaking the
p
(standing for proportion) parameter within bothgrob_row()
andgrob_col()
. - The default for
p
is 1, but sizes change ifp
differs from that.
grob_layout(
grob_row(p = 1, border = TRUE, grob_col('1')),
grob_row(p = 2, border = TRUE, grob_col('2')),
height = 100,
width = 100
) %>%
view_grob()
- The grob-row with
p = 2
is given twice the height of the grob-row withp = 1
. - The user can also supply specific heights/widths in millimeters.
grob_layout(
grob_row(height = 25, border = TRUE, grob_col('1')),
grob_row(height = 50, border = TRUE, grob_col('2')),
grob_row(height = 25, border = TRUE, grob_col('3')),
height = 100,
width = 100,
padding = 0
) %>%
view_grob()
- Or the user can use a combination of specific heights and proportions to size the grobs:
grob_layout(
grob_row(p = 3, border = TRUE, grob_col('1')),
grob_row(height = 50, border = TRUE, grob_col('2')),
grob_row(p = 1, border = TRUE, grob_col('3')),
height = 100,
width = 100
) %>%
view_grob()
Matrix Grobs
- Using the
aes_list
parameter and thega_list()
function withingrob_col()
, the aesthetics of individual grobs can be adjusted to how the user intends them to appear. - Run
?grobblR::ga_list
for a full list and description for each of the possible aesthetic options. - For uniform background color for each cell in a matrix, one option is inputting a single value for
background_color
as an element withinaes_list
:
mat = matrix(1:4, nrow = 2, byrow = TRUE)
grob_layout(
grob_row(grob_col(mat, aes_list = ga_list(background_color = "gray90"))),
height = 100,
width = 100
) %>%
view_grob()
- If the user wants different cells of the matrix to have different aesthetics, the user can utilize
grob_matrix()
andalter_at()
. - The use can alter specific cells / groups of cells, and different aesthetics with
alter_at()
once thegrob_matrix()
object is initialized. - Run
vignette("grob_matrix")
for more information ongrob_matrix()
.
mat %>%
grob_matrix() %>%
alter_at(~ "red", columns = 1, aesthetic = "text_color") %>%
alter_at(~ "blue", columns = 2, rows = 2, aesthetic = "background_color") %>%
alter_at(~ "white", columns = 2, rows = 2, aesthetic = "text_color") %>%
view_grob()
ggplot Grobs
- The
ggplot2
plot is stretched or squished depending on what the dimensions of the allotted space are:
data(iris)
library(ggplot2)
gg1 = ggplot(
data = iris,
mapping = aes(x = Sepal.Length, y = Sepal.Width, color = Species)
) +
geom_point() +
guides(color = FALSE)
#> Warning: `guides(<scale> = FALSE)` is deprecated. Please use `guides(<scale> =
#> "none")` instead.
gg2 = ggplot(
data = iris,
mapping = aes(x = Sepal.Length, y = Petal.Length, color = Species)
) +
geom_point() +
guides(color = FALSE)
#> Warning: `guides(<scale> = FALSE)` is deprecated. Please use `guides(<scale> =
#> "none")` instead.
grob_layout(
grob_row(grob_col(gg1), grob_col(gg2)),
grob_row(grob_col(gg1))
) %>%
view_grob(height = 100, width = 100)
Image Grobs
- Only images in .png format are allowed in grobblR. The user must provide either a valid file path or a valid URL to the image.
- If the user does not want to maintain the aspect ratio of the image and allow it to be stretched within its allotted space,
maintain_aspect_ratio = FALSE
must be inserted within theaes_list
list.
grob_layout(
grob_row(
border = TRUE,
grob_col(
border = TRUE,
'vignettes/kings_logo.png'
),
grob_col(
border = TRUE,
aes_list = ga_list(
maintain_aspect_ratio = FALSE
),
'https://raw.githubusercontent.com/calvinmfloyd/grobblR/master/vignettes/kings_logo.png'
)
),
height = 100,
width = 100
) %>%
view_grob()
- Or the user can incorporate
grob_image()
andadd_structure()
.
grob_layout(
grob_row(
border = TRUE,
grob_col(
border = TRUE,
'vignettes/kings_logo.png'
),
grob_col(
border = TRUE,
'https://raw.githubusercontent.com/calvinmfloyd/grobblR/master/vignettes/kings_logo.png' %>%
grob_image() %>%
add_structure("maintain_aspect_ratio", FALSE)
)
),
height = 100,
width = 100
) %>%
view_grob()
Text Grobs
- grobblR handles long character strings by making the text as big as possible, while still being able to fit the text inside its allotted space.
- This results in automatically putting different words on different lines:
text = "The quick brown fox jumps over the lazy dog."
grob_layout(
grob_row(
border = TRUE,
grob_col(
border = TRUE,
text
)
),
height = 100,
width = 100
) %>%
view_grob()
- The aesthetics of the text can be tweaked with
grob_text()
andadd_aesthetic()
.
grob_layout(
grob_row(
border = TRUE,
grob_col(
border = TRUE,
text %>%
grob_text() %>%
add_aesthetic("text_color", "blue") %>%
add_aesthetic("font_face", "italic")
)
),
height = 100,
width = 100
) %>%
view_grob()
Empty Space Grobs
- Empty space grobs in case the user needs to compact, or shift grobs around:
df = data.frame(letter = letters[1:5], col1 = 1:5, col2 = 5:1)
grob_layout(
grob_row(
border = TRUE,
grob_col(df),
grob_col(
grob_row(grob_col(df)),
grob_row(grob_col(p = 1/3, NA))
),
grob_col(
grob_row(grob_col(p = 1/3, NA)),
grob_row(grob_col(df))
)
),
height = 100,
width = 100
) %>%
view_grob()
Grob Layout to PDF
- The default values for the
height
andwidth
parameters withingrob_layout()
are280
millimeters and216
millimeters, as these are the values needed to properly fit the grob-layout onto a piece of standard computer paper, portrait orientation. - Converting multiple grob-layout’s into a single PDF report using
grob_to_pdf()
, with a file title and a meta data title:
first_page_grob_layout = grob_layout(
grob_row(
border = TRUE,
grob_col(df),
grob_col(
grob_row(grob_col(df)),
grob_row(grob_col(p = 1/3, NA))
),
grob_col(
grob_row(grob_col(p = 1/3, NA)),
grob_row(grob_col(df))
)
),
height = 100,
width = 100
)
second_page_grob_layout = grob_layout(
grob_row(
border = TRUE,
grob_col(
border = TRUE,
text
)
),
height = 100,
width = 100
)
# grob_to_pdf(
# first_page_grob_layout,
# second_page_grob_layout,
# file_name = file.path(tempdir(), "test.pdf"),
# meta_data_title = "Test PDF"
# )
# OR
grob_to_pdf(
list(first_page_grob_layout, second_page_grob_layout),
file_name = file.path(tempdir(), "test.pdf"),
meta_data_title = "Test PDF"
)