Merge 1ce8ef1 into 5fbbf5e

NAMESPACE

@@ -24,3 +24,5 @@ exportMethods(subtitles)
 import(dplyr)
 import(formatters)
 import(methods)
+importFrom(utils,head)
+importFrom(utils,tail)

R/rlistings.R

@@ -1,6 +1,7 @@
 #' @import formatters
 #' @import dplyr
 #' @import methods
+#' @importFrom utils head tail
 NULL
 
 setOldClass(c("listing_df", "data.frame"))

vignettes/rlistings.Rmd

@@ -1,5 +1,6 @@
 ---
 title: "Getting Started with rlistings"
+author: "Emily de la Rua and Gabriel Becker"
 date: "2022-10-26"
 output:
     rmarkdown::html_document:
@@ -48,6 +49,9 @@ The `rlistings` package is intended for use in creating simple one-dimensional l
 
 With the basic framework provided in this package, a `data.frame` object can be easily converted into a listing using the `as_listing` function with several optional customizations available.
 
+A listing, at its core, is a set of observation-level data which is to be rendered with particular formatting but without any sort of aggregation or further analysis. In practice, this translates to to a classed `data.frame` (or `tbl_df`) object with a specialized print method. This means that, unlike tables created with `rlistings`' sibling package `rtables`, a listing object is fundamentally the incoming `data.frame` with a few annotations attached to it.
+
+
 In the R code below we will give a basic example of how to create an `rlistings` listing from a pre-processed data frame.
 
 We first load in the `rlistings` package.
@@ -64,14 +68,14 @@ adae <- formatters::ex_adae
 
 Now we will create our listing.
 
-The `df` parameter sets our `data.frame` object. The `cols` argument takes a vector of names of any columns taken from the data frame that should be included in the listing. Column headers are set by the `label` attribute of each given variable. If there is no label associated with a given variable then the variable name will be taken as a header instead. For this example we will choose 8 random columns to display - 5 specific to the patient and 3 relating to the adverse event.
+The `df` parameter sets our `data.frame` object. The `cols` argument takes a vector of names of any columns taken from the data frame that should be included in the listing. Column headers are set by the `label` attribute of each given variable. If there is no label associated with a given variable then the variable name will be taken as a header instead. For this example we will choose 8 arbitrary columns to display - 5 specific to the patient and 3 relating to the adverse event.
 
 Since the dataset consists of 1934 rows in total, we will use the `head` function to print only the first 15 rows of the listing.
 
 ```{r}
 lsting <- as_listing(
   df = adae,
-  cols = c("USUBJID", "AGE", "SEX", "RACE", "ARM", "AEDECOD", "AESEV", "AETOXGR")
+  cols = c("USUBJID", "AETOXGR", "ARM", "AGE", "SEX", "RACE", "AEDECOD", "AESEV"),
 )
 
 head(lsting, 15)
@@ -81,27 +85,29 @@ In the listing output above you can see that there are several rows associated w
 
 ## Key Columns
 
-To tidy the listing and avoid repeatedly printing the same values in subsequent columns, the `key_cols` argument can take a vector of names of columns that should be treated as key columns in a listing. The data frame is sorted on the key columns and data repeated across all key columns for any subsequent rows will not be printed. You should note that any key columns set must also be included in the `cols` argument to be displayed in the listing. Below we implement key columns to clean up repeated patient-identifying information for improved readability.
+Key columns act as contextual identifiers for observations. Their core behavioral feature is that sequentially repeated values are not displayed. The `key_cols` argument takes a vector of column names identifying the key columns for the listing.
+
+A listing is always sorted by its key columns (with order defining the sort precedence). Any key columns set must also be included in the `cols` argument to be displayed in the listing. Below we specify trial arm and patient ID as key columns to improve readability.
 
 ```{r}
 lsting <- as_listing(
   df = adae,
-  cols = c("USUBJID", "AGE", "SEX", "RACE", "ARM", "AEDECOD", "AESEV", "AETOXGR"),
-  key_cols = c("USUBJID", "AGE", "SEX", "RACE", "ARM")
+  cols = c("USUBJID", "AETOXGR", "ARM", "AGE", "SEX", "RACE", "AEDECOD", "AESEV"),
+  key_cols = c( "USUBJID", "AETOXGR")
 )
 
 head(lsting, 15)
 ```
 
-## Titles and Footnotes
+## Titles and Footers
 
 Additionally, an `rlistings` listing can be annotated with two types of header information (main title and subtitles) and two types of footer information (main footers and provenance footers). A single title can be set using the `main_title` argument, while one or more subtitles, main footers, and provenance footers can be set by the `subtitles`, `main_footer` and `prov_footer` arguments respectively. These are demonstrated in the following updated listing.
 
 ```{r}
 lsting <- as_listing(
   df = adae,
-  cols = c("USUBJID", "AGE", "SEX", "RACE", "ARM", "AEDECOD", "AESEV", "AETOXGR"),
-  key_cols = c("USUBJID", "AGE", "SEX", "RACE", "ARM"),
+  cols = c("USUBJID", "AETOXGR", "ARM", "AGE", "SEX", "RACE", "AEDECOD", "AESEV"),
+  key_cols = c( "USUBJID", "AETOXGR"),
   main_title = "Main Title",
   subtitles = c("Subtitle A", "Subtitle B"),
   main_footer = c("Main Footer A", "Main Footer B", "Main Footer C"),