as_listing {rlistings} | R Documentation |
Create a listing from a data.frame
or tibble
Description
Create listings displaying key_cols
and disp_cols
to produce a compact and
elegant representation of the input data.frame
or tibble
.
Usage
as_listing(
df,
key_cols = names(df)[1],
disp_cols = NULL,
non_disp_cols = NULL,
sort_cols = key_cols,
unique_rows = FALSE,
default_formatting = list(all = fmt_config()),
col_formatting = NULL,
align_colnames = FALSE,
add_trailing_sep = NULL,
trailing_sep = " ",
main_title = NULL,
subtitles = NULL,
main_footer = NULL,
prov_footer = NULL,
split_into_pages_by_var = NULL,
spanning_col_labels = no_spans_df
)
spanning_col_label_df(df)
spanning_col_label_df(df) <- value
as_keycol(vec)
is_keycol(vec)
get_keycols(df)
listing_dispcols(df)
add_listing_dispcol(df, new)
listing_dispcols(df) <- value
align_colnames(df)
align_colnames(df) <- value
add_listing_col(
df,
name,
fun = NULL,
format = NULL,
na_str = "NA",
align = "left"
)
Arguments
df |
( |
key_cols |
( |
disp_cols |
( |
non_disp_cols |
( |
sort_cols |
( |
unique_rows |
( |
default_formatting |
( |
col_formatting |
( |
align_colnames |
( |
add_trailing_sep |
( |
trailing_sep |
( |
main_title |
( |
subtitles |
( |
main_footer |
( |
prov_footer |
( |
split_into_pages_by_var |
( |
spanning_col_labels |
( |
value |
( |
vec |
( |
new |
( |
name |
( |
fun |
( |
format |
( |
na_str |
( |
align |
( |
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 during 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.
Spanning column labels are displayed centered above the individual labels
of the columns they span across. span_level
1 is placed directly above
the column labels, with higher "span_levels' displayed above it in ascending
order.
IF spanning column labels are present, a single spanning label cannot span across both key and non-key displayed columns simultaneously due to key columns' repetition after page breaks during horizontal pagination. Attempting to set a spanning column label which does so will result in an error.
Value
A listing_df
object, sorted by its key columns.
df
with name
created (if necessary) and marked for
display during rendering.
Note
Unlike in the rtables
sister package, spanning labels here are purely
decorative and do not reflect any structure among the columns modeled by
rlistings
. Thus, we cannot, e.g., use pathing to select columns under
a certain spanning column label, or restrict horizontal pagination to
leave 'groups' of columns implied by a spanning label intact.
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 = "<No data>",
align = "right"
)
)
) %>%
add_listing_col("BMRKR1", format = "xx.x", align = "center")
mat <- matrix_form(lsting)
cat(toString(mat))