Advanced Usage of pharmaRTF

Introduction

This vignette will focus on a few more intricate features of the pharmaRTF package. After reviewing this document, you should have a good idea of how to get the most out of pharmaRTF. Specifically, this vignette covers:

• Understanding document orientation within pharmaRTF
• Multi-level column headers
• Minimizing cell padding
• Setting spacing between column headers and titles
• Split titles
• Special titles/footnote formats

A Small Note

Some of the syntax we use throughout this document uses the %>% pipe operator. This is to display support for a tidyverse style of coding. You can find the %>% operator in the magittr package.

Understanding Document Orientation Within pharmaRTF

In development of this feature, we realized as a team that the orientation of an RTF document has a bit of room for confusion. This spawns from the fact that within Microsoft Word, orientation is automatically determined by the document height and width, despite there being a keyword within RTF syntax that specifies landscape orientation. That said, we believe the most intuitive way to set the orientation of a document is with a property function, which in pharmaRTF is simply orientation()/set_orientation().

The default orientation of a pharmaRTF document is landscape, as this is typically what you would use on the clinical reports that the package is designed for. orientation is closely tied with the page_size attribute. When the orientation of an rtf_doc object is set to landscape, the height and width of the pagesize attribute will write out as specified in the object, with height writing to the height document property and width writing to the width property.

ht <- huxtable::as_hux(iris, add_colnames=TRUE) %>% 
  huxtable::set_width(1.2)

doc <- rtf_doc(ht)
pagesize(doc)
#>  width height 
#>   11.0    8.5

When you switch the orientation to ‘portrait’, the height and width properties will not change. Rather, when the actual RTF document is written out, the height and width will be reversed, effectively flipping the document on its side.

doc <- rtf_doc(ht) %>% 
  # Set orientation to portrait
  set_orientation('portrait')

# Page size does not change
pagesize(doc)
#>  width height 
#>   11.0    8.5

So why not switch the height and width properties in the object? This opens the door for inadvertent confusion. Consider the case where a user changes the orientation of the document. At that point, assume you switched the height and width. Next, the user manually sets height and width themselves. At this point, the change in orientation would be overridden by whatever height and width the user chooses manually. This is why we decided to only have the reversal happen at the time of writing the RTF code. Note that height and width will always align with the object default, which is landscape. But the document itself will write out with portrait orientation.

After changing the orientation, you can see that the height and the width have switched in the output document, and the document is in portrait orientation

Multi-level Column Headers

A common requirement of tables is to have spanning column headers. When columns need to be grouped in presentation, this is common practice. This requires a combination of work within huxtable and pharmaRTF. The first thing you need to do is create your huxtable object. For more details on how to do this, see the huxtable tips vignette.

# Create the column headers data frame
column_headers <- data.frame(
  Species = c("", "Species of Flower"),
  Sepal.Length = c("Sepal", "Length"),
  Sepal.Width = c("", "Width"),
  Petal.Length = c("Petal", "Length"),
  Petal.Width = c("", "Width"),
  stringsAsFactors = FALSE
)

# Create the huxtable table
ht <- huxtable::as_hux(rbind(column_headers, iris)) %>% 
  # Merge the Sepal cell over the Length and Width
  huxtable::merge_cells(1, 2:3) %>% 
  # Merge the Petal cell over the Length and Width
  huxtable::merge_cells(1, 4:5) %>% 
  # Align the top cells for both Sepal and Petal
  huxtable::set_align(1,2, 'center') %>% 
  huxtable::set_align(1,4, 'center') %>% 
  # Bold all the column header rows
  huxtable::set_bold(1:2, 1:ncol(iris), TRUE) %>% 
  # Bottom border on 1st column header row 
  huxtable::set_bottom_border(1, 2:4, 1) %>% 
  # Bottom border on 2nd row
  huxtable::set_bottom_border(2, 1:ncol(iris), 2) %>% 
  # Set the page width
  huxtable::set_width(1.5)

ht[1:10,]

Once the huxtable table is created with your multiple rows of column headers, incorporating it into your rtf_doc object is simple. Just use the header_rows argument when creating your RTF doc.

doc <- rtf_doc(ht, header_rows=2)

write_rtf(doc, file="table6.rtf")

Below you can see that the 2 rows of column headers have been pulled into the header of the document and are repeating from page to page.

New in pharmaRTF v0.1.1, header_rows now additionally offers the capability to prevent column headers from being pulled into the RTF document header. You can do this as follows:

# Method 1
doc <- rtf_doc(ht, header_rows=0)

# Method 2
doc <- rtf_doc(ht) %>% 
  set_header_rows(0)

write_rtf(doc, file="table6.rtf")

Minimizing Cell Padding

An odd quirk of RTF documents is the method in which they do cell padding. The default output actually uses a minimal amount of cell padding, but when looking at your display, it may still be too large for your personal preference of the display. But fear not! We have a method to help minimize the cell padding further.

The root of the issue is that RTF documents have two methods for handling cell padding. You can read more about this within the Details section of the ignore_cell_padding() function. From a user perspective, it is simply a matter of adding one more line into the creation of your rtf_doc object.

doc <- rtf_doc(ht, header_rows=2) %>% 
  set_ignore_cell_padding(TRUE)

# Or avoiding piping
ignore_cell_padding(doc) <- TRUE

write_rtf(doc, file="table7.rtf")

Setting Spacing Between Column Headers and Titles

Depending your display, you may want to have a gap between your titles and the column headers, or potentially space below the column headers and the start of the body of the table. One way to deal with this could be to add blank title lines or blank rows to your table - but that would be a hacky fix and less than ideal. This is why the column_header_buffer attribute exists in the rtf_doc object.

column_header_buffer() sets the buffer of spaces you want above and below the column headers.

doc <- rtf_doc(ht, header_rows=2) %>% 
  set_ignore_cell_padding(TRUE) %>% 
  set_column_header_buffer(top=2, bottom=1) %>% 
  add_titles(hf_line("The Iris Dataset", bold=TRUE, font_size=20))


write_rtf(doc, file="table8.rtf")

Split Titles

Very often, we have tiles in clinical reports where there’s text that flushes left and right on the same line. pharmaRTF has a method to handle this within the hf_line object for titles and footnotes. hf_line objects have two spaces available within the text element:

hf_line('Text1', 'Text2')
#> $text
#> [1] "Text1" "Text2"
#> 
#> attr(,"align")
#> [1] "center"
#> attr(,"bold")
#> [1] FALSE
#> attr(,"italic")
#> [1] FALSE
#> attr(,"font")
#> [1] NA
#> attr(,"font_size")
#> [1] NA
#> attr(,"index")
#> [1] NA
#> attr(,"class")
#> [1] "hf_line"

When the alignment is set to center, left, or right, these elements will simply concatenate. But when the alignment is set to ‘split’, the first text alignment will align on the left and the second on the right. This enables you to do those split titles and footnotes that you will often see within reports.

doc <- rtf_doc(ht, header_rows=2) %>% 
  add_titles(hf_line("I'm on the left", "I'm on the right", bold=TRUE, align='split'))


write_rtf(doc, file="table9.rtf")

Special Title/Footnote Formats

The hf_line object has three keywords that trigger special behavior within titles and footnotes. These are:

• PAGE_FORMAT:
• DATE_FORMAT:
• FILE_PATH:

When the text of a title/footnote starts with these keywords (note that it must start with this text), it triggers a special action. The text can either be in the first or second text element. Each one of these warrants some further explanation on their own.

hf_line('PAGE_FORMAT: Page %s of %s")

hf_line('PAGE_FORMAT: %s | %s")

hf_line('PAGE_FORMAT: Page %s")

doc <- rtf_doc(ht, header_rows=2) %>% 
  add_titles(hf_line("PAGE_FORMAT: Page %s of %s", bold=TRUE, align='right'))


write_rtf(doc, file="table10.rtf")

doc <- rtf_doc(ht, header_rows=2) %>% 
  add_titles(hf_line("Text on the left", "PAGE_FORMAT: Page %s of %s", bold=TRUE, align='split'))


write_rtf(doc, file="table11.rtf")

hf_line("DATE_FORMAT: %Y-%m-%dT%H:%M:%S")

doc <- rtf_doc(ht, header_rows=2) %>% 
  add_titles(hf_line("Text on the left", "DATE_FORMAT: %Y-%m-%dT%H:%M:%S", bold=TRUE, align='split'))


write_rtf(doc, file="table12.rtf")

doc <- rtf_doc(ht, header_rows=2) %>% 
  add_titles(hf_line("Text on the left", "DATE_FORMAT: Document run on %H:%M %A, %B %d, %Y", bold=TRUE, align='split'))


write_rtf(doc, file="table13.rtf")

doc <- rtf_doc(ht, header_rows=2) %>% 
  add_titles(hf_line("Text on the left", "FILE_PATH: Run from: %s", bold=TRUE, align='split'))


write_rtf(doc, file="table14.rtf")

source('file_path_example.r')

Further Reading

If you have not already reviewed them, be sure to check out our other vignettes!

• To pick up the basics of using pharmaRTF, see vignette("pharmaRTF")
• To learn tips and tricks for using huxtable with pharmaRTF, see vignette("huxtable_tips")
• To learn more advanced usage of pharmaRTF, see vignette("advanced_usage")