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
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.
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.
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,]
| Species | Sepal.Length | Petal.Length |
| Sepal | | Petal | |
| Species of Flower | Length | Width | Length | Width |
| setosa | 5.1 | 3.5 | 1.4 | 0.2 |
| setosa | 4.9 | 3 | 1.4 | 0.2 |
| setosa | 4.7 | 3.2 | 1.3 | 0.2 |
| setosa | 4.6 | 3.1 | 1.5 | 0.2 |
| setosa | 5 | 3.6 | 1.4 | 0.2 |
| setosa | 5.4 | 3.9 | 1.7 | 0.4 |
| setosa | 4.6 | 3.4 | 1.4 | 0.3 |
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.
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:
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.
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.
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:
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.
