diff --git a/DESCRIPTION b/DESCRIPTION index 4e05d704..71e45c23 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -21,7 +21,7 @@ URL: https://insightsengineering.github.io/rlistings/, https://github.com/insightsengineering/rlistings/ BugReports: https://github.com/insightsengineering/rlistings/issues Depends: - formatters (>= 0.5.5.9005), + formatters (>= 0.5.5.9018), methods, tibble (>= 2.0.0) Imports: diff --git a/NEWS.md b/NEWS.md index e41ee193..f6d9c718 100644 --- a/NEWS.md +++ b/NEWS.md @@ -7,6 +7,7 @@ variable. This enables page splits by variable when paginating. * Removed defunct function `pag_listing_indices`. * Refactored `paginate_listing` to use directly `paginate_to_mpfs` function from `formatters` package. + * Remove defunct function `pag_listing_indices`. ## rlistings 0.2.7 * Applied `styler` and resolved package lint. Changed default indentation from 4 spaces to 2. diff --git a/R/listing_export.R b/R/listing_export.R index 5af4c9d3..5f8ac89f 100644 --- a/R/listing_export.R +++ b/R/listing_export.R @@ -1,14 +1,16 @@ #' @importFrom formatters export_as_txt #' -#' @export #' @examples #' dat <- ex_adae +#' #' lsting <- as_listing(dat[1:25, ], key_cols = c("USUBJID", "AESOC")) %>% #' 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 = " / ")) #' main_title(lsting) <- "this is some title" #' main_footer(lsting) <- "this is some footer" +#' #' cat(export_as_txt(lsting, file = NULL, paginate = TRUE)) #' +#' @export formatters::export_as_txt diff --git a/R/paginate_listing.R b/R/paginate_listing.R index 863a129c..468cace6 100644 --- a/R/paginate_listing.R +++ b/R/paginate_listing.R @@ -15,7 +15,7 @@ #' to include per page. Standard is `70` while `NULL` disables vertical pagination. #' @param cpp (`numeric(1)` or `NULL`)\cr width (in characters) of the pages for horizontal #' pagination. `NULL` (the default) indicates no horizontal pagination should be done. -#' @param print_pages (`logical(1)`)\cr whether to also print the paginated listing to console +#' @param print_pages (`flag`)\cr whether the paginated listing should be printed to the console #' (`cat(toString(x))`). #' #' @return A list of `listing_df` objects where each list element corresponds to a separate page. @@ -24,7 +24,6 @@ #' dat <- ex_adae #' lsting <- as_listing(dat[1:25, ], disp_cols = c("USUBJID", "AESOC", "RACE", "AETOXGR", "BMRKR1")) #' mat <- matrix_form(lsting) -#' #' cat(toString(mat)) #' #' paginate_listing(lsting, lpp = 10) diff --git a/R/rlistings.R b/R/rlistings.R index 300f3729..a95ba723 100644 --- a/R/rlistings.R +++ b/R/rlistings.R @@ -1,50 +1,47 @@ setOldClass(c("listing_df", "tbl_df", "tbl", "data.frame")) setOldClass(c("MatrixPrintForm", "list")) -#' @rdname listings -#' @title Create a Listing from a `data.frame` or `tibble` +#' Create a listing from a `data.frame` or `tibble` #' #' @description `r lifecycle::badge("experimental")` #' -#' Creates listings by using `cols` and `key_cols` to produce a compact and -#' elegant representation of the `data.frame` or `tibble` in input. +#' Create listings displaying `key_cols` and `disp_cols` to produce a compact and +#' elegant representation of the input `data.frame` or `tibble`. #' -#' @param df data.frame or listing_df. The (non-listing) data.frame to be converted to a listing or -#' the listing_df to be modified. -#' @param key_cols character. Names of columns which should be treated as *key columns* +#' @param df (`data.frame` or `listing_df`)\cr the `data.frame` to be converted to a listing or +#' `listing_df` to be modified. +#' @param key_cols (`character`)\cr vector of names of columns which should be treated as *key columns* #' when rendering the listing. Key columns allow you to group repeat occurrences. -#' @param 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 +#' @param disp_cols (`character` or `NULL`)\cr vector of 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`. -#' @param 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. -#' @param unique_rows logical(1). Should only unique rows be included in the listing. Defaults to `FALSE`. -#' @param 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`. -#' @param 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`. -#' @param main_title character(1) or NULL. The main title for the listing, or -#' `NULL` (the default). Must be length 1 non-NULL. -#' @param subtitles character or NULL. A vector of subtitle(s) for the -#' listing, or `NULL` (the default). -#' @param main_footer character or NULL. A vector of main footer lines -#' for the listing, or `NULL` (the default). -#' @param 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. -#' @param split_into_pages_by_var character or NULL. The name of a column for which the -#' listing should be split into pages, one for each level of the column. Check +#' @param non_disp_cols (`character` or `NULL`)\cr vector of names of non-key columns to be excluded as display +#' columns. All other non-key columns are treated as display columns. Ignored if `disp_cols` is non-`NULL`. +#' @param unique_rows (`flag`)\cr whether only unique rows should be included in the listing. Defaults to `FALSE`. +#' @param default_formatting (`list`)\cr 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`. +#' @param col_formatting (`list`)\cr 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`. +#' @param main_title (`string` or `NULL`)\cr the main title for the listing, or `NULL` (the default). +#' @param subtitles (`character` or `NULL`)\cr a vector of subtitles for the listing, or `NULL` (the default). +#' @param main_footer (`character` or `NULL`)\cr a vector of main footer lines for the listing, or `NULL` (the default). +#' @param prov_footer (`character` or `NULL`)\cr a vector of provenance footer lines for the listing, or `NULL` +#' (the default). Each string element is placed on a new line. +#' @param split_into_pages_by_var (`character` or `NULL`)\cr the name of a variable for on the listing should be split +#' into pages, with each page corresponding to one unique value/level of the variable. See #' [split_into_pages_by_var()] for more details. -#' @param vec any. A column vector from a `listing_df` to be annotated as a key column. +#' @param vec (`string`)\cr name of a column vector from a `listing_df` object to be annotated as a key column. #' -#' @return A `listing_df` object, sorted by the key columns. +#' @return A `listing_df` object, sorted by its key columns. #' -#' @details At its core, a `listing_df` object is a `tbl_df` object with a customized +#' @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. #' @@ -54,9 +51,9 @@ setOldClass(c("MatrixPrintForm", "list")) #' #' All key columns are also display columns. #' -#' `listing_df` objects are always sorted by their set of key_columns at creation time. +#' `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 +#' 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 @@ -73,7 +70,6 @@ setOldClass(c("MatrixPrintForm", "list")) #' within the object available for computations but *are not rendered during #' printing or export of the listing*. #' -#' #' @examples #' dat <- ex_adae #' @@ -131,6 +127,7 @@ setOldClass(c("MatrixPrintForm", "list")) #' cat(toString(mat)) #' #' @export +#' @rdname listings as_listing <- function(df, key_cols = names(df)[1], disp_cols = NULL, @@ -242,7 +239,6 @@ as_listing <- function(df, df } - #' @export #' @rdname listings as_keycol <- function(vec) { @@ -255,15 +251,12 @@ as_keycol <- function(vec) { vec } - #' @export #' @rdname listings is_keycol <- function(vec) { inherits(vec, "listing_keycol") } - - #' @export #' @rdname listings get_keycols <- function(df) { @@ -271,19 +264,19 @@ get_keycols <- function(df) { } #' @inherit formatters::matrix_form -#' @seealso [formatters::matrix_form()] -#' @param indent_rownames logical(1). Silently ignored, as listings do not have row names +#' @param indent_rownames (`flag`)\cr silently ignored, as listings do not have row names #' nor indenting structure. +#' @param expand_newlines (`flag`)\cr this should always be `TRUE` for listings. We keep it +#' for debugging reasons. +#' +#' @return a [`MatrixPrintForm`] object. +#' +#' @seealso [formatters::matrix_form()] #' #' @examples #' lsting <- as_listing(mtcars) #' mf <- matrix_form(lsting) #' -#' @return a `MatrixPrintForm` object -#' -#' @note Parameter `expand_newlines` should always be `TRUE` for listings. We keep it for -#' debugging reasons. -#' #' @export setMethod( "matrix_form", "listing_df", @@ -298,7 +291,6 @@ setMethod( attributes(listing) <- atts keycols <- get_keycols(listing) - bodymat <- matrix("", nrow = nrow(listing), ncol = ncol(listing) @@ -306,7 +298,6 @@ setMethod( colnames(bodymat) <- names(listing) - curkey <- "" for (i in seq_along(keycols)) { kcol <- keycols[i] @@ -326,7 +317,6 @@ setMethod( } } - fullmat <- rbind( var_labels(listing, fill = TRUE), bodymat @@ -369,21 +359,23 @@ setMethod( } ) - #' @export #' @rdname listings listing_dispcols <- function(df) attr(df, "listing_dispcols") %||% character() +#' @param new (`character`)\cr vector of names of columns to be added to +#' the set of display columns. +#' #' @export -#' @param new character. Names of columns to be added to -#' the set of display columns. #' @rdname listings add_listing_dispcol <- function(df, new) { listing_dispcols(df) <- c(listing_dispcols(df), new) df } + +#' @param value (`string`)\cr new value. +#' #' @export -#' @param value character. New value. #' @rdname listings `listing_dispcols<-` <- function(df, value) { if (!is.character(value)) { @@ -403,22 +395,18 @@ add_listing_dispcol <- function(df, new) { df } - - -#' @rdname listings -#' -#' @param name character(1). Name of the existing or new column to be -#' displayed when the listing is rendered. -#' @param fun function or NULL. A function which accepts \code{df} and -#' returns the vector for a new column, which is added to \code{df} as -#' \code{name}, or NULL if marking an existing column as -#' a listing column. #' @inheritParams formatters::fmt_config +#' @param name (`string`)\cr name of the existing or new column to be +#' displayed when the listing is rendered. +#' @param fun (`function` or `NULL`)\cr 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. #' -#' @return `df`, with `name` created (if necessary) and marked for +#' @return `df` with `name` created (if necessary) and marked for #' display during rendering. #' #' @export +#' @rdname listings add_listing_col <- function(df, name, fun = NULL, diff --git a/R/rlistings_methods.R b/R/rlistings_methods.R index 1c73458b..52816faf 100644 --- a/R/rlistings_methods.R +++ b/R/rlistings_methods.R @@ -11,14 +11,15 @@ #' Methods for `listing_df` objects #' -#' See core documentation in \code{formatters} for descriptions -#' of these functions. +#' See core documentation in [`formatters`] for descriptions of these functions. #' -#' @export #' @inheritParams formatters::toString -#' @param x listing_df. The listing. -#' @param ... dots. See `toString` method in \code{formatters} for all parameters. +#' @param x (`listing_df`)\cr the listing. +#' @param ... additional parameters passed to [formatters::toString()]. +#' #' @method print listing_df +#' +#' @export #' @name listing_methods print.listing_df <- function(x, widths = NULL, tf_wrap = FALSE, max_width = NULL, ...) { cat(toString(matrix_form(x), widths = widths, tf_wrap = tf_wrap, max_width = max_width, ...)) @@ -44,11 +45,12 @@ basic_run_lens <- function(x) { diff(c(0L, i)) } - +#' @param df (`listing_df`)\cr the listing. +#' @param colnm (`string`)\cr column name. +#' @param colvec (`vector`)\cr column values based on `colnm`. +#' #' @rdname vec_nlines -#' @param df listing_df. The listing. -#' @param colnm Column name -#' @param colvec Column values based on colnm +#' @keywords internal format_colvector <- function(df, colnm, colvec = df[[colnm]]) { if (missing(colvec) && !(colnm %in% names(df))) { stop("column ", colnm, " not found") @@ -67,17 +69,17 @@ format_colvector <- function(df, colnm, colvec = df[[colnm]]) { #' For `vec_nlines`, calculate the number of lines each element of a column vector will #' take to render. For `format_colvector`, #' -#' @param vec any vector. A column vector to be rendered into ASCII. -#' @param max_width numeric (or NULL). The width the column will be -#' rendered in. -#' @return a numeric vector of the number of lines elementwise that -#' will be needed to render the elements of \code{vec} to width -#' \code{max_width}. +#' @param vec (`vector`)\cr a column vector to be rendered into ASCII. +#' @param max_width (`numeric(1)` or `NULL`)\cr the width to render the column with. +#' @return (`numeric`)\cr a vector of the number of lines element-wise that will be +#' needed to render the elements of `vec` to width `max_width`. +#' #' @keywords internal setGeneric("vec_nlines", function(vec, max_width = NULL) standardGeneric("vec_nlines")) +#' @param vec (`vector`)\cr a vector. +#' #' @rdname vec_nlines -#' @param vec A vector. #' @keywords internal setMethod("vec_nlines", "ANY", function(vec, max_width = NULL) { if (is.null(max_width)) { @@ -100,19 +102,22 @@ setMethod("vec_nlines", "ANY", function(vec, max_width = NULL) { ## ret[is.na(ret)] <- format_value(NA_character ## }) -#' Make pagination dataframe for a listing -#' @export +#' Make pagination data frame for a listing +#' #' @inheritParams formatters::make_row_df -#' @param tt listing_df. The listing to be rendered -#' @param visible_only logical(1). Ignored, as listings -#' do not have non-visible structural elements. +#' @param tt (`listing_df`)\cr the listing to be rendered. +#' @param visible_only (`flag`)\cr ignored, as listings do not have +#' non-visible structural elements. +#' +#' @return a `data.frame` with pagination information. +#' +#' @seealso [formatters::make_row_df()] #' #' @examples #' lsting <- as_listing(mtcars) #' mf <- matrix_form(lsting) #' -#' @return a data.frame with pagination information. -#' @seealso \code{\link[formatters]{make_row_df}} +#' @export setMethod( "make_row_df", "listing_df", function(tt, colwidths = NULL, visible_only = TRUE, @@ -216,14 +221,14 @@ setMethod( ## ret ## }) -#' @export -#' @param x listing_df. The listing. #' @inheritParams base::Extract -#' @param i ANY. Passed to base `[` methods. -#' @param j ANY. Passed to base `[` methods. +#' @param x (`listing_df`)\cr the listing. +#' @param i (`any`)\cr object passed to base `[` methods. +#' @param j (`any`)\cr object passed to base `[` methods. +#' +#' @export #' @aliases [,listing_df-method #' @rdname listing_methods -#' @keywords internal setMethod( "[", "listing_df", function(x, i, j, drop = FALSE) { @@ -238,17 +243,19 @@ setMethod( ) #' @rdname listing_methods -#' @param obj The object. -#' @export -#' @return for getter methods, the value of the aspect of -#' \code{obj}; for setter methods, \code{obj} with -#' the relevant element of the listing updated. +#' @param obj (`listing_df`)\cr the listing. +#' +#' @return +#' * Accessor methods return the value of the aspect of `obj`. +#' * Setter methods return `obj` with the relevant element of the listing updated. #' #' @examples #' lsting <- as_listing(mtcars) #' main_title(lsting) <- "Hi there" #' #' main_title(lsting) +#' +#' @export setMethod( "main_title", "listing_df", function(obj) attr(obj, "main_title") %||% character() @@ -260,12 +267,14 @@ setMethod( "subtitles", "listing_df", function(obj) attr(obj, "subtitles") %||% character() ) + #' @rdname listing_methods #' @export setMethod( "main_footer", "listing_df", function(obj) attr(obj, "main_footer") %||% character() ) + #' @rdname listing_methods #' @export setMethod( diff --git a/inst/WORDLIST b/inst/WORDLIST index b1ce3613..ece60666 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -14,8 +14,8 @@ customizations de df droppage +formatter funder -getter pagesize pre repo diff --git a/man/listing_methods.Rd b/man/listing_methods.Rd index 65b8a96c..1bf99d8f 100644 --- a/man/listing_methods.Rd +++ b/man/listing_methods.Rd @@ -41,28 +41,24 @@ \S4method{num_rep_cols}{listing_df}(obj) } \arguments{ -\item{x}{listing_df. The listing.} +\item{x}{(\code{listing_df})\cr the listing.} -\item{widths}{numeric (or \code{NULL}). (proposed) widths for the columns -of \code{x}. The expected length of this numeric vector can be -retrieved with \code{ncol() + 1} as the column of row names must -also be considered.} +\item{widths}{(\code{numeric} or \code{NULL})\cr Proposed widths for the columns of \code{x}. The expected +length of this numeric vector can be retrieved with \code{ncol(x) + 1} as the column of row names +must also be considered.} -\item{tf_wrap}{logical(1). Should the texts for title, subtitle, -and footnotes be wrapped?} +\item{tf_wrap}{(\code{flag})\cr whether the text for title, subtitles, and footnotes should be wrapped.} -\item{max_width}{integer(1), character(1) or \code{NULL}. Width that title -and footer (including footnotes) materials should be -word-wrapped to. If \code{NULL}, it is set to the current print width -of the session (\code{getOption("width")}). If set to \code{"auto"}, -the width of the table (plus any table inset) is used. Ignored -completely if \code{tf_wrap} is \code{FALSE}.} +\item{max_width}{(\code{integer(1)}, \code{string} or \code{NULL})\cr width that title and footer (including +footnotes) materials should be word-wrapped to. If \code{NULL}, it is set to the current print width of the +session (\code{getOption("width")}). If set to \code{"auto"}, the width of the table (plus any table inset) is +used. Parameter is ignored if \code{tf_wrap = FALSE}.} -\item{...}{dots. See \code{toString} method in \code{formatters} for all parameters.} +\item{...}{additional parameters passed to \code{\link[formatters:tostring]{formatters::toString()}}.} -\item{i}{ANY. Passed to base \code{[} methods.} +\item{i}{(\code{any})\cr object passed to base \code{[} methods.} -\item{j}{ANY. Passed to base \code{[} methods.} +\item{j}{(\code{any})\cr object passed to base \code{[} methods.} \item{drop}{For matrices and arrays. If \code{TRUE} the result is coerced to the lowest possible dimension (see the examples). This @@ -70,24 +66,24 @@ completely if \code{tf_wrap} is \code{FALSE}.} \code{\link[base]{drop}} for further details. } -\item{obj}{The object.} +\item{obj}{(\code{listing_df})\cr the listing.} \item{value}{typically an array-like \R object of a similar class as \code{x}.} } \value{ -for getter methods, the value of the aspect of -\code{obj}; for setter methods, \code{obj} with -the relevant element of the listing updated. +\itemize{ +\item Accessor methods return the value of the aspect of \code{obj}. +\item Setter methods return \code{obj} with the relevant element of the listing updated. +} } \description{ -See core documentation in \code{formatters} for descriptions -of these functions. +See core documentation in \code{\link{formatters}} for descriptions of these functions. } \examples{ lsting <- as_listing(mtcars) main_title(lsting) <- "Hi there" main_title(lsting) + } -\keyword{internal} diff --git a/man/listings.Rd b/man/listings.Rd index db0096ac..80b653be 100644 --- a/man/listings.Rd +++ b/man/listings.Rd @@ -9,7 +9,7 @@ \alias{add_listing_dispcol} \alias{listing_dispcols<-} \alias{add_listing_col} -\title{Create a Listing from a \code{data.frame} or \code{tibble}} +\title{Create a listing from a \code{data.frame} or \code{tibble}} \usage{ as_listing( df, @@ -48,81 +48,77 @@ add_listing_col( ) } \arguments{ -\item{df}{data.frame or listing_df. The (non-listing) data.frame to be converted to a listing or -the listing_df to be modified.} +\item{df}{(\code{data.frame} or \code{listing_df})\cr the \code{data.frame} to be converted to a listing or +\code{listing_df} to be modified.} -\item{key_cols}{character. Names of columns which should be treated as \emph{key columns} +\item{key_cols}{(\code{character})\cr vector of names of columns which should be treated as \emph{key columns} when rendering the listing. Key columns allow you to group repeat occurrences.} -\item{disp_cols}{character or NULL. Names of non-key columns which should be displayed when -the listing is rendered. Defaults to all columns of \code{df} not named in \code{key_cols} or +\item{disp_cols}{(\code{character} or \code{NULL})\cr vector of names of non-key columns which should be +displayed when the listing is rendered. Defaults to all columns of \code{df} not named in \code{key_cols} or \code{non_disp_cols}.} -\item{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 -\code{disp_cols} is non-NULL.} +\item{non_disp_cols}{(\code{character} or \code{NULL})\cr vector of names of non-key columns to be excluded as display +columns. All other non-key columns are treated as display columns. Ignored if \code{disp_cols} is non-\code{NULL}.} -\item{unique_rows}{logical(1). Should only unique rows be included in the listing. Defaults to \code{FALSE}.} +\item{unique_rows}{(\code{flag})\cr whether only unique rows should be included in the listing. Defaults to \code{FALSE}.} -\item{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 \code{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 \code{fmt_config} can take 3 arguments: \code{format}, \code{na_str}, and \code{align}.} +\item{default_formatting}{(\code{list})\cr 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 \code{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 \code{fmt_config} can take 3 arguments: \code{format}, \code{na_str}, +and \code{align}.} -\item{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 \code{fmt_config} with the formatting configuration that should be implemented for that column. Objects of type -\code{fmt_config} can take 3 arguments: \code{format}, \code{na_str}, and \code{align}. Defaults to \code{NULL}.} +\item{col_formatting}{(\code{list})\cr 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 \code{fmt_config} with the formatting configuration that should be implemented for that column. Objects +of type \code{fmt_config} can take 3 arguments: \code{format}, \code{na_str}, and \code{align}. Defaults to \code{NULL}.} -\item{main_title}{character(1) or NULL. The main title for the listing, or -\code{NULL} (the default). Must be length 1 non-NULL.} +\item{main_title}{(\code{string} or \code{NULL})\cr the main title for the listing, or \code{NULL} (the default).} -\item{subtitles}{character or NULL. A vector of subtitle(s) for the -listing, or \code{NULL} (the default).} +\item{subtitles}{(\code{character} or \code{NULL})\cr a vector of subtitles for the listing, or \code{NULL} (the default).} -\item{main_footer}{character or NULL. A vector of main footer lines -for the listing, or \code{NULL} (the default).} +\item{main_footer}{(\code{character} or \code{NULL})\cr a vector of main footer lines for the listing, or \code{NULL} (the default).} -\item{prov_footer}{character or NULL. A vector of provenance strings -for the listing, or \code{NULL} (the default). Each string element is placed on a new line.} +\item{prov_footer}{(\code{character} or \code{NULL})\cr a vector of provenance footer lines for the listing, or \code{NULL} +(the default). Each string element is placed on a new line.} -\item{split_into_pages_by_var}{character or NULL. The name of a column for which the -listing should be split into pages, one for each level of the column. Check +\item{split_into_pages_by_var}{(\code{character} or \code{NULL})\cr the name of a variable for on the listing should be split +into pages, with each page corresponding to one unique value/level of the variable. See \code{\link[=split_into_pages_by_var]{split_into_pages_by_var()}} for more details.} -\item{vec}{any. A column vector from a \code{listing_df} to be annotated as a key column.} +\item{vec}{(\code{string})\cr name of a column vector from a \code{listing_df} object to be annotated as a key column.} -\item{new}{character. Names of columns to be added to +\item{new}{(\code{character})\cr vector of names of columns to be added to the set of display columns.} -\item{value}{character. New value.} +\item{value}{(\code{string})\cr new value.} -\item{name}{character(1). Name of the existing or new column to be +\item{name}{(\code{string})\cr name of the existing or new column to be displayed when the listing is rendered.} -\item{fun}{function or NULL. A function which accepts \code{df} and +\item{fun}{(\code{function} or \code{NULL})\cr a function which accepts \code{df} and returns the vector for a new column, which is added to \code{df} as -\code{name}, or NULL if marking an existing column as -a listing column.} +\code{name}, or \code{NULL} if marking an existing column as a listing column.} -\item{format}{character(1) or function. A format label (string) or \code{formatter} function.} +\item{format}{(\code{string} or \code{function})\cr a format label (string) or formatter function.} -\item{na_str}{character(1). String that should be displayed in place of missing values.} +\item{na_str}{(\code{string})\cr string that should be displayed in place of missing values.} -\item{align}{character(1). Alignment values should be rendered with.} +\item{align}{(\code{string})\cr alignment values should be rendered with.} } \value{ -A \code{listing_df} object, sorted by the key columns. +A \code{listing_df} object, sorted by its key columns. -\code{df}, with \code{name} created (if necessary) and marked for +\code{df} with \code{name} created (if necessary) and marked for display during rendering. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} -Creates listings by using \code{cols} and \code{key_cols} to produce a compact and -elegant representation of the \code{data.frame} or \code{tibble} in input. +Create listings displaying \code{key_cols} and \code{disp_cols} to produce a compact and +elegant representation of the input \code{data.frame} or \code{tibble}. } \details{ At its core, a \code{listing_df} object is a \code{tbl_df} object with a customized @@ -135,9 +131,9 @@ Key columns act as indexes, which means a number of things in practice. All key columns are also display columns. -\code{listing_df} objects are always sorted by their set of key_columns at creation time. +\code{listing_df} objects are always sorted by their set of key columns at creation time. Any \code{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 +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 diff --git a/man/make_row_df-listing_df-method.Rd b/man/make_row_df-listing_df-method.Rd index cdc2183f..5de8782b 100644 --- a/man/make_row_df-listing_df-method.Rd +++ b/man/make_row_df-listing_df-method.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/rlistings_methods.R \name{make_row_df,listing_df-method} \alias{make_row_df,listing_df-method} -\title{Make pagination dataframe for a listing} +\title{Make pagination data frame for a listing} \usage{ \S4method{make_row_df}{listing_df}( tt, @@ -19,35 +19,34 @@ ) } \arguments{ -\item{tt}{listing_df. The listing to be rendered} +\item{tt}{(\code{listing_df})\cr the listing to be rendered.} -\item{colwidths}{numeric. Internal detail do not set manually.} +\item{colwidths}{(\code{numeric})\cr internal detail, do not set manually.} -\item{visible_only}{logical(1). Ignored, as listings -do not have non-visible structural elements.} +\item{visible_only}{(\code{flag})\cr ignored, as listings do not have +non-visible structural elements.} -\item{rownum}{numeric(1). Internal detail do not set manually.} +\item{rownum}{(\code{numeric(1)})\cr internal detail, do not set manually.} -\item{indent}{integer(1). Internal detail do not set manually.} +\item{indent}{(\code{integer(1)})\cr internal detail, do not set manually.} -\item{path}{character. Path to the (sub)table represented by -\code{tt}. Defaults to \code{character()}} +\item{path}{(\code{character})\cr path to the (sub)table represented by \code{tt}. Defaults to \code{character()}.} -\item{incontent}{logical(1). Internal detail do not set manually.} +\item{incontent}{(\code{flag})\cr internal detail, do not set manually.} -\item{repr_ext}{integer(1). Internal detail do not set manually.} +\item{repr_ext}{(\code{integer(1)})\cr internal detail, do not set manually.} -\item{repr_inds}{integer. Internal detail do not set manually.} +\item{repr_inds}{(\code{integer})\cr internal detail, do not set manually.} -\item{sibpos}{integer(1). Internal detail do not set manually.} +\item{sibpos}{(\code{integer(1)})\cr internal detail, do not set manually.} -\item{nsibs}{integer(1). Internal detail do not set manually.} +\item{nsibs}{(\code{integer(1)})\cr internal detail, do not set manually.} } \value{ -a data.frame with pagination information. +a \code{data.frame} with pagination information. } \description{ -Make pagination dataframe for a listing +Make pagination data frame for a listing } \examples{ lsting <- as_listing(mtcars) @@ -55,5 +54,5 @@ mf <- matrix_form(lsting) } \seealso{ -\code{\link[formatters]{make_row_df}} +\code{\link[formatters:make_row_df]{formatters::make_row_df()}} } diff --git a/man/matrix_form-listing_df-method.Rd b/man/matrix_form-listing_df-method.Rd index a84f4ad4..010bb658 100644 --- a/man/matrix_form-listing_df-method.Rd +++ b/man/matrix_form-listing_df-method.Rd @@ -7,31 +7,20 @@ \S4method{matrix_form}{listing_df}(obj, indent_rownames = FALSE, expand_newlines = TRUE) } \arguments{ -\item{obj}{ANY. Object to be transformed into a ready-to-render form (a \code{MatrixPrintForm} object)} +\item{obj}{(\code{ANY})\cr object to be transformed into a ready-to-render form (a \code{\link[formatters]{MatrixPrintForm}} object).} -\item{indent_rownames}{logical(1). Silently ignored, as listings do not have row names +\item{indent_rownames}{(\code{flag})\cr silently ignored, as listings do not have row names nor indenting structure.} -\item{expand_newlines}{logical(1). Should the matrix form generated -expand rows whose values contain newlines into multiple -'physical' rows (as they will appear when rendered into -ASCII). Defaults to \code{TRUE}} +\item{expand_newlines}{(\code{flag})\cr this should always be \code{TRUE} for listings. We keep it +for debugging reasons.} } \value{ -a \code{MatrixPrintForm} object +a \code{\link{MatrixPrintForm}} object. } \description{ -Although \code{rtables} are represented as a tree data structure when outputting the table to ASCII or HTML it is -useful to map the \code{rtable} to an in between state with the formatted cells in a matrix form. -} -\details{ -The strings in the return object are defined as follows: row labels are those determined by \code{summarize_rows} and -cell values are determined using \code{get_formatted_cells}. -(Column labels are calculated using a non-exported internal function. -} -\note{ -Parameter \code{expand_newlines} should always be \code{TRUE} for listings. We keep it for -debugging reasons. +Although \code{rtable}s are represented as a tree data structure when outputting the table to ASCII or HTML, +it is useful to map the \code{rtable} to an in-between state with the formatted cells in a matrix form. } \examples{ lsting <- as_listing(mtcars) diff --git a/man/paginate.Rd b/man/paginate.Rd index 53542fd6..5b8e2162 100644 --- a/man/paginate.Rd +++ b/man/paginate.Rd @@ -27,30 +27,27 @@ paginate_listing( \arguments{ \item{lsting}{(\code{listing_df} or \code{list})\cr the listing or list of listings to paginate.} -\item{page_type}{character(1). Name of a page type. See -\code{page_types}. Ignored when \code{pg_width} and \code{pg_height} -are set directly.} +\item{page_type}{(\code{string})\cr name of a page type. See \code{\link[formatters]{page_types}}. Ignored +when \code{pg_width} and \code{pg_height} are set directly.} -\item{font_family}{character(1). Name of a font family. An error -will be thrown if the family named is not monospaced. Defaults -to Courier.} +\item{font_family}{(\code{string})\cr name of a font family. An error will be thrown +if the family named is not monospaced. Defaults to \code{"Courier"}.} -\item{font_size}{numeric(1). Font size, defaults to 12.} +\item{font_size}{(\code{numeric(1)})\cr font size. Defaults to \code{12}.} -\item{lineheight}{numeric(1). Line height, defaults to 1.} +\item{lineheight}{(\code{numeric(1)})\cr line height. Defaults to \code{1}.} -\item{landscape}{logical(1). Should the dimensions of \code{page_type} -be inverted for landscape? Defaults to \code{FALSE}, ignored when -\code{pg_width} and \code{pg_height} are set directly.} +\item{landscape}{(\code{flag})\cr whether the dimensions of \code{page_type} should be +inverted for landscape orientation. Defaults to \code{FALSE}, ignored when \code{pg_width} and +\code{pg_height} are set directly.} -\item{pg_width}{numeric(1). Page width in inches.} +\item{pg_width}{(\code{numeric(1)})\cr page width in inches.} -\item{pg_height}{numeric(1). Page height in inches.} +\item{pg_height}{(\code{numeric(1)})\cr page height in inches.} -\item{margins}{numeric(4). Named numeric vector containing \code{'bottom'}, -\code{'left'}, \code{'top'}, and \code{'right'} margins in inches. Defaults -to \code{.5} inches for both vertical margins and \code{.75} for both -horizontal margins.} +\item{margins}{(\code{numeric(4)})\cr named numeric vector containing \code{"bottom"}, \code{"left"}, +\code{"top"}, and \code{"right"} margins in inches. Defaults to \code{.5} inches for both vertical +margins and \code{.75} for both horizontal margins.} \item{lpp}{(\code{numeric(1)} or \code{NULL})\cr number of rows/lines (excluding titles and footers) to include per page. Standard is \code{70} while \code{NULL} disables vertical pagination.} @@ -58,26 +55,22 @@ to include per page. Standard is \code{70} while \code{NULL} disables vertical p \item{cpp}{(\code{numeric(1)} or \code{NULL})\cr width (in characters) of the pages for horizontal pagination. \code{NULL} (the default) indicates no horizontal pagination should be done.} -\item{colwidths}{numeric vector. Column widths (in characters) for -use with vertical pagination.} +\item{colwidths}{(\code{numeric})\cr vector of column widths (in characters) for use in vertical pagination.} -\item{tf_wrap}{logical(1). Should the texts for title, subtitle, -and footnotes be wrapped?} +\item{tf_wrap}{(\code{flag})\cr whether the text for title, subtitles, and footnotes should be wrapped.} -\item{rep_cols}{numeric(1). Number of \emph{columns} (not including -row labels) to be repeated on every page. Defaults to 0} +\item{rep_cols}{(\code{numeric(1)})\cr number of \emph{columns} (not including row labels) to be repeated on every page. +Defaults to 0.} -\item{max_width}{integer(1), character(1) or \code{NULL}. Width that title -and footer (including footnotes) materials should be -word-wrapped to. If \code{NULL}, it is set to the current print width -of the session (\code{getOption("width")}). If set to \code{"auto"}, -the width of the table (plus any table inset) is used. Ignored -completely if \code{tf_wrap} is \code{FALSE}.} +\item{max_width}{(\code{integer(1)}, \code{string} or \code{NULL})\cr width that title and footer (including +footnotes) materials should be word-wrapped to. If \code{NULL}, it is set to the current print width of the +session (\code{getOption("width")}). If set to \code{"auto"}, the width of the table (plus any table inset) is +used. Parameter is ignored if \code{tf_wrap = FALSE}.} -\item{verbose}{logical(1). Should additional informative messages about the search for -pagination breaks be shown. Defaults to \code{FALSE}.} +\item{verbose}{(\code{flag})\cr whether additional informative messages about the search for +pagination breaks should be shown. Defaults to \code{FALSE}.} -\item{print_pages}{(\code{logical(1)})\cr whether to also print the paginated listing to console +\item{print_pages}{(\code{flag})\cr whether the paginated listing should be printed to the console (\code{cat(toString(x))}).} } \value{ @@ -94,7 +87,6 @@ rows and/or horizontal if there are many columns. This function is a wrapper of dat <- ex_adae lsting <- as_listing(dat[1:25, ], disp_cols = c("USUBJID", "AESOC", "RACE", "AETOXGR", "BMRKR1")) mat <- matrix_form(lsting) - cat(toString(mat)) paginate_listing(lsting, lpp = 10) diff --git a/man/reexports.Rd b/man/reexports.Rd index 529792d7..1006b197 100644 --- a/man/reexports.Rd +++ b/man/reexports.Rd @@ -7,12 +7,14 @@ \title{Objects exported from other packages} \examples{ dat <- ex_adae + lsting <- as_listing(dat[1:25, ], key_cols = c("USUBJID", "AESOC")) \%>\% 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 = " / ")) main_title(lsting) <- "this is some title" main_footer(lsting) <- "this is some footer" + cat(export_as_txt(lsting, file = NULL, paginate = TRUE)) } diff --git a/man/vec_nlines.Rd b/man/vec_nlines.Rd index 810bbcc1..c34c3d7d 100644 --- a/man/vec_nlines.Rd +++ b/man/vec_nlines.Rd @@ -13,21 +13,19 @@ vec_nlines(vec, max_width = NULL) \S4method{vec_nlines}{ANY}(vec, max_width = NULL) } \arguments{ -\item{df}{listing_df. The listing.} +\item{df}{(\code{listing_df})\cr the listing.} -\item{colnm}{Column name} +\item{colnm}{(\code{string})\cr column name.} -\item{colvec}{Column values based on colnm} +\item{colvec}{(\code{vector})\cr column values based on \code{colnm}.} -\item{vec}{A vector.} +\item{vec}{(\code{vector})\cr a vector.} -\item{max_width}{numeric (or NULL). The width the column will be -rendered in.} +\item{max_width}{(\code{numeric(1)} or \code{NULL})\cr the width to render the column with.} } \value{ -a numeric vector of the number of lines elementwise that -will be needed to render the elements of \code{vec} to width -\code{max_width}. +(\code{numeric})\cr a vector of the number of lines element-wise that will be +needed to render the elements of \code{vec} to width \code{max_width}. } \description{ For \code{vec_nlines}, calculate the number of lines each element of a column vector will diff --git a/tests/testthat/test-export.R b/tests/testthat/test-export.R index 1ae74c45..3923034d 100644 --- a/tests/testthat/test-export.R +++ b/tests/testthat/test-export.R @@ -24,7 +24,6 @@ testthat::test_that("key columns repeat with export_as_txt", { testthat::expect_snapshot(cat(listing_exp)) }) - testthat::test_that("key columns repeat with pagination with export_as_txt", { # pre-processing and ordering tbl <- as_listing( diff --git a/tests/testthat/test-listings.R b/tests/testthat/test-listings.R index c72acce6..125f7da8 100644 --- a/tests/testthat/test-listings.R +++ b/tests/testthat/test-listings.R @@ -17,7 +17,6 @@ testthat::test_that("Column labels are the same", { ) }) - testthat::test_that("listings work well with different formats and attributes", { # (1) Error with NA values in numeric column when apply format anl_tmp <- anl @@ -132,7 +131,6 @@ testthat::test_that("regression test for keycols being lost due to `head()`", { ) }) - testthat::test_that("column inclusion and ordering stuff", { ## key columns must be left-most k columns (#36) lsting <- as_listing( diff --git a/tests/testthat/test-paginate_listing.R b/tests/testthat/test-paginate_listing.R index b7531229..80ba7fa0 100644 --- a/tests/testthat/test-paginate_listing.R +++ b/tests/testthat/test-paginate_listing.R @@ -169,7 +169,6 @@ testthat::test_that("pagination: lpp and cpp correctly computed for margins", { testthat::expect_identical(res, pag) }) - testthat::test_that("pagination works with col wrapping", { lsting <- h_lsting_adae(disp_cols = c("USUBJID", "AESOC", "RACE")) diff --git a/tests/testthat/test-print.R b/tests/testthat/test-print.R index 4396bdda..c1f1283d 100644 --- a/tests/testthat/test-print.R +++ b/tests/testthat/test-print.R @@ -18,6 +18,7 @@ testthat::test_that("Listing print correctly with different widths", { testthat::expect_snapshot(cat(toString(matrix_form(lsting), widths = c(7, 8, 9), hsep = "-"))) }) + testthat::test_that("as_listing produces correct output when default_formatting is specified", { anl$BMRKR1[3:6] <- NA lsting <- as_listing(