rlistings (version 0.2.7)

as_listing: Create a Listing from a data.frame or tibble

Description

Creates listings by using cols and key_cols to produce a compact and elegant representation of the data.frame or tibble in input.

Usage

as_listing(
  df,
  key_cols = names(df)[1],
  disp_cols = NULL,
  non_disp_cols = NULL,
  unique_rows = FALSE,
  default_formatting = list(all = fmt_config()),
  col_formatting = NULL,
  main_title = NULL,
  subtitles = NULL,
  main_footer = NULL,
  prov_footer = NULL
)
as_keycol(vec)
is_keycol(vec)
get_keycols(df)
listing_dispcols(df)
add_listing_dispcol(df, new)
listing_dispcols(df) <- value
add_listing_col(
  df,
  name,
  fun = NULL,
  format = NULL,
  na_str = "NA",
  align = "left"
)

Value

A listing_df object, sorted by the key columns.

df, with name created (if necessary) and marked for display during rendering.

Arguments

df

data.frame or listing_df. The (non-listing) data.frame to be converted to a listing or the listing_df to be modified.

key_cols

character. Names of columns which should be treated as key columns when rendering the listing. Key columns allow you to group repeat occurrences.

disp_cols

character or NULL. Names of non-key columns which should be displayed when the listing is rendered. Defaults to all columns of df not named in key_cols or non_disp_cols.

non_disp_cols

character or NULL. Names of non-key columns to be excluded as display columns. All other non-key columns are then treated as display columns. Invalid if disp_cols is non-NULL.

unique_rows

logical(1). Should only unique rows be included in the listing. Defaults to FALSE.

default_formatting

list. A named list of default column format configurations to apply when rendering the listing. Each name-value pair consists of a name corresponding to a data class (or "numeric" for all unspecified numeric classes) and a value of type fmt_config with the format configuration that should be implemented for columns of that class. If named element "all" is included in the list, this configuration will be used for all data classes not specified. Objects of type fmt_config can take 3 arguments: format, na_str, and align.

col_formatting

list. A named list of custom column formatting configurations to apply to specific columns when rendering the listing. Each name-value pair consists of a name corresponding to a column name and a value of type fmt_config with the formatting configuration that should be implemented for that column. Objects of type fmt_config can take 3 arguments: format, na_str, and align. Defaults to NULL.

main_title

character(1) or NULL. The main title for the listing, or NULL (the default). Must be length 1 non-NULL.

subtitles

character or NULL. A vector of subtitle(s) for the listing, or NULL (the default).

main_footer

character or NULL. A vector of main footer lines for the listing, or NULL (the default).

prov_footer

character or NULL. A vector of provenance strings for the listing, or NULL (the default). Each string element is placed on a new line.

vec

any. A column vector from a listing_df to be annotated as a key column.

new

character. Names of columns to be added to the set of display columns.

value

character. New value.

name

character(1). Name of the existing or new column to be displayed when the listing is rendered.

fun

function or NULL. A function which accepts df and returns the vector for a new column, which is added to df as name, or NULL if marking an existing column as a listing column.

format

character(1) or function. A format label (string) or formatter function.

na_str

character(1). String that should be displayed in place of missing values.

align

character(1). Alignment values should be rendered with.

Details

At its core, a listing_df object is a tbl_df object with a customized print method and support for the formatting and pagination machinery provided by the formatters package.

listing_df objects have two 'special' types of columns: key columns and display columns.

Key columns act as indexes, which means a number of things in practice.

All key columns are also display columns.

listing_df objects are always sorted by their set of key_columns at creation time. Any listing_df object which is not sorted by its full set of key columns (e.g., one whose rows have been reordered explicitly creation) is invalid and the behavior when rendering or paginating that object is undefined.

Each value of a key column is printed only once per page and per unique combination of values for all higher-priority (i.e., to the left of it) key columns. Locations where a repeated value would have been printed within a key column for the same higher-priority-key combination on the same page are rendered as empty space. Note, determination of which elements to display within a key column at rendering is based on the underlying value; any non-default formatting applied to the column has no effect on this behavior.

Display columns are columns which should be rendered, but are not key columns. By default this is all non-key columns in the incoming data, but in need not be. Columns in the underlying data which are neither key nor display columns remain within the object available for computations but are not rendered during printing or export of the listing.

Examples

dat <- ex_adae

# This example demonstrates the listing with key_cols (values are grouped by USUBJID) and
# multiple lines in prov_footer
lsting <- as_listing(dat[1:25, ],
  key_cols = c("USUBJID", "AESOC"),
  main_title = "Example Title for Listing",
  subtitles = "This is the subtitle for this Adverse Events Table",
  main_footer = "Main footer for the listing",
  prov_footer = c(
    "You can even add a subfooter", "Second element is place on a new line",
    "Third string"
  )
) %>%
  add_listing_col("AETOXGR") %>%
  add_listing_col("BMRKR1", format = "xx.x") %>%
  add_listing_col("AESER / AREL", fun = function(df) paste(df$AESER, df$AREL, sep = " / "))

mat <- matrix_form(lsting)

cat(toString(mat))

# This example demonstrates the listing table without key_cols
# and specifying the cols with disp_cols.
dat <- ex_adae
lsting <- as_listing(dat[1:25, ],
  disp_cols = c("USUBJID", "AESOC", "RACE", "AETOXGR", "BMRKR1")
)

mat <- matrix_form(lsting)

cat(toString(mat))

# This example demonstrates a listing with format configurations specified
# via the default_formatting and col_formatting arguments
dat <- ex_adae
dat$AENDY[3:6] <- NA
lsting <- as_listing(dat[1:25, ],
  key_cols = c("USUBJID", "AESOC"),
  disp_cols = c("STUDYID", "SEX", "ASEQ", "RANDDT", "ASTDY", "AENDY"),
  default_formatting = list(
    all = fmt_config(align = "left"),
    numeric = fmt_config(
      format = "xx.xx",
      na_str = "",
      align = "right"
    )
  )
) %>%
  add_listing_col("BMRKR1", format = "xx.x", align = "center")

mat <- matrix_form(lsting)

cat(toString(mat))