rlistings coverage - 84.79%

Files
Source

## #' Print a listing to the terminal
## #' @param x listing_df. the listing
## #' @param ... ANY. unused
## #' @return prints the listing object to the screen and silently returns the object
## #' @export
## setMethod("print", "listing_df",
##           function(x, ...) {
##     cat(toString(listing_matrix_form(x)))
##     invisible(x)
## })

#' Methods for `listing_df` objects
#'
#' See core documentation in [`formatters`] for descriptions of these functions.
#'
#' @inheritParams formatters::toString
#' @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, ...))
  invisible(x)
}

#' @exportMethod toString
#' @name listing_methods
#' @aliases toString,listing_df-method
setMethod("toString", "listing_df", function(x, ...) {
  toString(matrix_form(x), ...)
})

## because rle in base is too much of a stickler for being atomic
basic_run_lens <- function(x) {
  n <- length(x)
  if (n == 0) {
    return(integer())
  }

  y <- x[-1L] != x[-n]
  i <- c(which(y), n)
  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
#' @keywords internal
format_colvector <- function(df, colnm, colvec = df[[colnm]]) {
  if (missing(colvec) && !(colnm %in% names(df))) {
    stop("column ", colnm, " not found")
  }
  na_str <- obj_na_str(colvec)
  if (is.null(na_str) || all(is.na(na_str))) {
    na_str <- rep("-", max(1L, length(na_str)))
  }

  strvec <- vapply(colvec, format_value, "", format = obj_format(colvec), na_str = na_str)
  strvec
}

#' Utilities for formatting a listing column
#'
#' For `vec_nlines`, calculate the number of lines each element of a column vector will
#' take to render. For `format_colvector`,
#'
#' @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
#' @keywords internal
setMethod("vec_nlines", "ANY", function(vec, max_width = NULL) {
  if (is.null(max_width)) {
    max_width <- floor(0.9 * getOption("width")) # default of base::strwrap
    # NB: flooring as it is used as <= (also in base::strwrap)
  }
  # in formatters for characters
  unlist(lapply(format_colvector(colvec = vec), nlines, max_width = max_width))
})

## setMethod("vec_nlines", "character", function(vec, max_width = NULL) {
##     strvec <- wrap_txt(format_colvector(colvec = vec), width = max_width, collapse = "\n")
##     mtchs <- gregexpr("\n", strvec, fixed = TRUE)
##     1L + vapply(mtchs, function(vi) sum(vi > 0), 1L)
## })

## setMethod("vec_nlines", "factor", function(vec, max_width = NULL) {
##   lvl_nlines <- vec_nlines(levels(vec), max_width = max_width)
##   ret <- lvl_nlines[vec]
##   ret[is.na(ret)] <- format_value(NA_character
## })

#' Make pagination data frame for a listing
#'
#' @inheritParams formatters::make_row_df
#' @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)
#'
#' @export
setMethod(
  "make_row_df", "listing_df",
  function(tt, colwidths = NULL, visible_only = TRUE,
           rownum = 0,
           indent = 0L,
           path = character(),
           incontent = FALSE,
           repr_ext = 0L,
           repr_inds = integer(),
           sibpos = NA_integer_,
           nsibs = NA_integer_) {
    ## assume sortedness by keycols
    keycols <- get_keycols(tt)
    dispcols <- listing_dispcols(tt)
    abs_rownumber <- seq_along(tt[[1]])
    if (length(keycols) >= 1) {
      runlens <- basic_run_lens(tt[[tail(keycols, 1)]])
    } else {
      runlens <- rep(1, NROW(tt))
    }
    sibpos <- unlist(lapply(runlens, seq_len))
    nsibs <- rep(runlens, times = runlens)
    extents <- rep(1L, nrow(tt))
    if (length(colwidths) > 0 && length(colwidths) != length(dispcols)) {
      stop(
        "Non-null colwidths vector must be the same length as the number of display columns.\n",
        "Got: ", length(colwidths), "(", length(dispcols), " disp cols)."
      )
    }
    if (length(colwidths) > 0) {
      names(colwidths) <- dispcols
    }
    ## extents is a row-wise vector of extents, for each col, we update
    ## if that column has any rows wider than the previously recorded extent.
    for (col in dispcols) {
      ## duplicated from matrix_form method, refactor!
      col_ext <- vec_nlines(tt[[col]], max_width = colwidths[col])
      extents <- ifelse(col_ext > extents, col_ext, extents)
    }
    ret <- data.frame(
      label = "", name = "",
      abs_rownumber = abs_rownumber,
      path = I(as.list(rep(NA_character_, NROW(tt)))),
      pos_in_siblings = sibpos,
      n_siblings = nsibs,
      self_extent = extents,
      par_extent = 0L,
      reprint_inds = I(replicate(NROW(tt), list(integer()))),
      node_class = "listing_df",
      indent = 0L,
      nrowrefs = 0L, ## XXX this doesn't support footnotes
      ncellrefs = 0L, ## XXX this doesn't support footnotes
      nreflines = 0L, ## XXX this doesn't support footnotes
      force_page = FALSE,
      page_title = NA_character_,
      trailing_sep = NA_character_
    )
    stopifnot(identical(
      names(ret),
      names(pagdfrow(
        nm = "", lab = "", rnum = 1L, pth = NA_character_, extent = 1L,
        rclass = ""
      ))
    ))
    ret
  }
)

##     tt$sibpos <- unlist(lapply(
##     ## don't support pathing for now
##     tt$path <- I(lapply(1:NROW(tt),
##                     function(i) {
##         retpath <- character(2*length(keycols))
##         for(j in seq_along(keycols)) {
##             retpath[2*j - 1] <- keycols[j]
##             retpath[2*j] <- tt[i, keycols[j], drop = TRUE]
##         }
##         retpath
##     }))
##     spl <- split(tt, tt[keycols])
##     spl <- spl[vapply(spl, function(y) NROW(y) > 0, NA)]
##     dfs <- lapply(spl, function(df) {
##         df <- df[order(df$abs_rownumber),]
##         ndf <- NROW(df)
##         lapply(1:ndf, function(i) {
##             rw <- df[i,]
##             stopifnot(nrow(rw) == 1)
##             pagdfrow(nm = "",
##                      lab = "",
##                      rnum = rw$abs_rownumber,
##                      pth = NA_character_,
##                      sibpos = i,
##                      nsibs = ndf,
##                      extent = 1L,
##                      rclass = "listing_df",
##                      repind = integer())
##         })
##     })
##     ret <- do.call(rbind, unlist(dfs, recursive = FALSE))
##     ret <- ret[order(ret$abs_rownumber),]
##     ret
## })

#' @inheritParams base::Extract
#' @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
setMethod(
  "[", "listing_df",
  function(x, i, j, drop = FALSE) {
    xattr <- attributes(x)
    xattr$names <- xattr$names[j]
    res <- NextMethod()
    if (!drop) {
      attributes(res) <- xattr
    }
    res
  }
)

#' @rdname listing_methods
#' @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()
)

#' @rdname listing_methods
#' @export
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(
  "prov_footer", "listing_df",
  function(obj) attr(obj, "prov_footer") %||% character()
)

.chk_value <- function(val, fname, len_one = FALSE, null_ok = TRUE) {
  if (null_ok && is.null(val)) {
    return(TRUE)
  }
  if (!is.character(val)) {
    stop("value for ", fname, " must be a character, got ",
      "object of class: ", paste(class(val), collapse = ","),
      call. = FALSE
    )
  }
  if (len_one && length(val) > 1) {
    stop(
      "value for ", fname, " must be length <= 1, got ",
      "vector of length ", length(val)
    )
  }
  TRUE
}

#' @rdname listing_methods
#' @export
setMethod(
  "main_title<-", "listing_df",
  function(obj, value) {
    ## length 1 restriction is to match rtables behavior
    ## which currently enforces this (though incompletely)
    .chk_value(value, "main_title", len_one = TRUE)
    attr(obj, "main_title") <- value
    obj
  }
)

#' @rdname listing_methods
#' @export
setMethod(
  "subtitles<-", "listing_df",
  function(obj, value) {
    .chk_value(value, "subtitles")
    attr(obj, "subtitles") <- value
    obj
  }
)

#' @rdname listing_methods
#' @export
setMethod(
  "main_footer<-", "listing_df",
  function(obj, value) {
    .chk_value(value, "main_footer")
    attr(obj, "main_footer") <- value
    obj
  }
)

#' @rdname listing_methods
#' @export
setMethod(
  "prov_footer<-", "listing_df",
  function(obj, value) {
    .chk_value(value, "prov_footer")
    attr(obj, "prov_footer") <- value
    obj
  }
)

#' @rdname listing_methods
#' @export
setMethod(
  "num_rep_cols", "listing_df",
  function(obj) {
    length(get_keycols(obj))
  }
)

setOldClass(c("listing_df", "tbl_df", "tbl", "data.frame"))
setOldClass(c("MatrixPrintForm", "list"))

#' Create a listing from a `data.frame` or `tibble`
#'
#' @description `r lifecycle::badge("experimental")`
#'
#' 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`)\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`)\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`)\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 (`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 its key columns.
#'
#' @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*.
#'
#' @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))
#'
#' @export
#' @rdname listings
as_listing <- function(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,
                       split_into_pages_by_var = NULL) {
  if (length(non_disp_cols) > 0 && length(intersect(key_cols, non_disp_cols)) > 0) {
    stop(
      "Key column also listed in non_disp_cols. All key columns are by",
      " definition display columns."
    )
  }
  if (!is.null(disp_cols) && !is.null(non_disp_cols)) {
    stop("Got non-null values for both disp_cols and non_disp_cols. This is not supported.")
  } else if (is.null(disp_cols)) {
    ## non_disp_cols NULL is ok here
    cols <- setdiff(names(df), c(key_cols, non_disp_cols))
  } else {
    ## disp_cols non-null, non_disp_cols NULL
    cols <- disp_cols
  }
  if (!all(sapply(default_formatting, is, class2 = "fmt_config"))) {
    stop(
      "All format configurations supplied in `default_formatting`",
      " must be of type `fmt_config`."
    )
  }
  if (!(is.null(col_formatting) || all(sapply(col_formatting, is, class2 = "fmt_config")))) {
    stop(
      "All format configurations supplied in `col_formatting`",
      " must be of type `fmt_config`."
    )
  }

  df <- as_tibble(df)
  varlabs <- var_labels(df, fill = TRUE)
  o <- do.call(order, df[key_cols])
  if (is.unsorted(o)) {
    if (interactive()) {
      message("sorting incoming data by key columns")
    }
    df <- df[o, ]
  }

  ## reorder the full set of cols to ensure key columns are first
  ordercols <- c(key_cols, setdiff(names(df), key_cols))
  df <- df[, ordercols]
  var_labels(df) <- varlabs[ordercols]

  for (cnm in key_cols) {
    df[[cnm]] <- as_keycol(df[[cnm]])
  }

  ## key cols must be leftmost cols
  cols <- c(key_cols, setdiff(cols, key_cols))

  row_all_na <- apply(df[cols], 1, function(x) all(is.na(x)))
  if (any(row_all_na)) {
    warning("rows that only contain NA values have been trimmed")
    df <- df[!row_all_na, ]
  }

  # set col format configs
  df[cols] <- lapply(cols, function(col) {
    col_class <- tail(class(df[[col]]), 1)
    col_fmt_class <- if (!col_class %in% names(default_formatting) && is.numeric(df[[col]])) "numeric" else col_class
    col_fmt <- if (col %in% names(col_formatting)) {
      col_formatting[[col]]
    } else if (col_fmt_class %in% names(default_formatting)) {
      default_formatting[[col_fmt_class]]
    } else {
      if (!"all" %in% names(default_formatting)) {
        stop(
          "Format configurations must be supplied for all listing columns. ",
          "To cover all remaining columns please add an 'all' configuration",
          " to `default_formatting`."
        )
      }
      default_formatting[["all"]]
    }
    # ANY attr <- fmt_config slot
    obj_format(df[[col]]) <- obj_format(col_fmt)
    obj_na_str(df[[col]]) <- if (is.null(obj_na_str(col_fmt))) "NA" else obj_na_str(col_fmt)
    obj_align(df[[col]]) <- if (is.null(obj_align(col_fmt))) "left" else obj_align(col_fmt)
    df[[col]]
  })

  if (unique_rows) df <- df[!duplicated(df[, cols]), ]

  class(df) <- c("listing_df", class(df))

  ## these all work even when the value is NULL
  main_title(df) <- main_title
  main_footer(df) <- main_footer
  subtitles(df) <- subtitles
  prov_footer(df) <- prov_footer
  listing_dispcols(df) <- cols

  if (!is.null(split_into_pages_by_var)) {
    df <- split_into_pages_by_var(df, split_into_pages_by_var)
  }

  df
}

#' @export
#' @rdname listings
as_keycol <- function(vec) {
  if (is.factor(vec)) {
    lab <- obj_label(vec)
    vec <- as.character(vec)
    obj_label(vec) <- lab
  }
  class(vec) <- c("listing_keycol", class(vec))
  vec
}

#' @export
#' @rdname listings
is_keycol <- function(vec) {
  inherits(vec, "listing_keycol")
}

#' @export
#' @rdname listings
get_keycols <- function(df) {
  names(which(sapply(df, is_keycol)))
}

#' @inherit formatters::matrix_form
#' @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)
#'
#' @export
setMethod(
  "matrix_form", "listing_df",
  rix_form <- function(obj, indent_rownames = FALSE, expand_newlines = TRUE) {
    ##  we intentionally silently ignore indent_rownames because listings have
    ## no rownames, but formatters::vert_pag_indices calls matrix_form(obj, TRUE)
    ## unconditionally.
    cols <- attr(obj, "listing_dispcols")
    listing <- obj[, cols]
    atts <- attributes(obj)
    atts$names <- cols
    attributes(listing) <- atts
    keycols <- get_keycols(listing)

    bodymat <- matrix("",
      nrow = nrow(listing),
      ncol = ncol(listing)
    )

    colnames(bodymat) <- names(listing)

    curkey <- ""
    for (i in seq_along(keycols)) {
      kcol <- keycols[i]
      kcolvec <- listing[[kcol]]
      kcolvec <- vapply(kcolvec, format_value, "", format = obj_format(kcolvec), na_str = obj_na_str(kcolvec))
      curkey <- paste0(curkey, kcolvec)
      disp <- c(TRUE, tail(curkey, -1) != head(curkey, -1))
      bodymat[disp, kcol] <- kcolvec[disp]
    }

    nonkeycols <- setdiff(names(listing), keycols)
    if (length(nonkeycols) > 0) {
      for (nonk in nonkeycols) {
        vec <- listing[[nonk]]
        vec <- vapply(vec, format_value, "", format = obj_format(vec), na_str = obj_na_str(vec))
        bodymat[, nonk] <- vec
      }
    }

    fullmat <- rbind(
      var_labels(listing, fill = TRUE),
      bodymat
    )

    colaligns <- rbind(
      rep("center", length(cols)),
      matrix(sapply(listing, obj_align),
        ncol = length(cols),
        nrow = nrow(fullmat) - 1,
        byrow = TRUE
      )
    )

    MatrixPrintForm(
      strings = fullmat,
      spans = matrix(1,
        nrow = nrow(fullmat),
        ncol = ncol(fullmat)
      ),
      ref_fnotes = list(),
      aligns = colaligns,
      formats = matrix(1,
        nrow = nrow(fullmat),
        ncol = ncol(fullmat)
      ),
      row_info = make_row_df(obj),
      listing_keycols = keycols, # It is always something
      nlines_header = 1, # We allow only one level of headers and nl expansion happens after
      nrow_header = 1,
      has_topleft = FALSE,
      has_rowlabs = FALSE,
      expand_newlines = expand_newlines,
      main_title = main_title(obj),
      subtitles = subtitles(obj),
      page_titles = page_titles(obj),
      main_footer = main_footer(obj),
      prov_footer = prov_footer(obj)
    )
  }
)

#' @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
#' @rdname listings
add_listing_dispcol <- function(df, new) {
  listing_dispcols(df) <- c(listing_dispcols(df), new)
  df
}

#' @param value (`string`)\cr new value.
#'
#' @export
#' @rdname listings
`listing_dispcols<-` <- function(df, value) {
  if (!is.character(value)) {
    stop(
      "dispcols must be a character vector of column names, got ",
      "object of class: ", paste(class(value), collapse = ",")
    )
  }
  chk <- setdiff(value, names(df)) ## remember setdiff is not symmetrical
  if (length(chk) > 0) {
    stop(
      "listing display columns must be columns in the underlying data. ",
      "Column(s) ", paste(chk, collapse = ", "), " not present in the data."
    )
  }
  attr(df, "listing_dispcols") <- unique(value)
  df
}

#' @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
#'   display during rendering.
#'
#' @export
#' @rdname listings
add_listing_col <- function(df,
                            name,
                            fun = NULL,
                            format = NULL,
                            na_str = "NA",
                            align = "left") {
  if (!is.null(fun)) {
    vec <- with_label(fun(df), name)
  } else if (name %in% names(df)) {
    vec <- df[[name]]
  } else {
    stop(
      "Column '", name, "' not found. name argument must specify an existing column when ",
      "no generating function (fun argument) is specified."
    )
  }

  if (!is.null(format)) {
    obj_format(vec) <- format
  }

  obj_na_str(vec) <- na_str
  obj_align(vec) <- align

  ## this works for both new and existing columns
  df[[name]] <- vec
  df <- add_listing_dispcol(df, name)
  df
}

#' Split Listing by Values of a Variable
#'
#' @description `r lifecycle::badge("experimental")`
#'
#' Split is performed based on unique values of the given parameter present in the listing.
#' Each listing can only be split by variable once. If this function is applied prior to
#' pagination, parameter values will be separated by page.
#'
#' @param lsting listing_df. The listing to split.
#' @param var character. Name of the variable to split on.
#' @param page_prefix character. Prefix to be appended with the split value (`var` level),
#'   at the end of the subtitles, corresponding to each resulting list element (listing).
#'
#' @return A list of `lsting_df` objects each corresponding to a unique value of `var`.
#'
#' @note This function should only be used after the complete listing has been created. The
#'   listing cannot be modified further after applying this function.
#'
#' @examples
#' dat <- ex_adae[1:20, ]
#'
#' lsting <- as_listing(
#'   dat,
#'   key_cols = c("USUBJID", "AGE"),
#'   disp_cols = "SEX",
#'   main_title = "title",
#'   main_footer = "footer"
#' ) %>%
#'   add_listing_col("BMRKR1", format = "xx.x") %>%
#'   split_into_pages_by_var("SEX")
#'
#' lsting
#'
#' @export
split_into_pages_by_var <- function(lsting, var, page_prefix = var) {
  checkmate::assert_class(lsting, "listing_df")
  checkmate::assert_choice(var, names(lsting))

  lsting_by_var <- list()
  for (lvl in unique(lsting[[var]])) {
    var_desc <- paste0(page_prefix, ": ", lvl)
    lsting_by_var[[lvl]] <- lsting[lsting[[var]] == lvl, ]
    subtitles(lsting_by_var[[lvl]]) <- c(subtitles(lsting), var_desc)
  }

  lsting_by_var
}

#' Paginate listings
#'
#' @description `r lifecycle::badge("experimental")`
#'
#' Pagination of a listing. This can be vertical for long listings with many
#' rows and/or horizontal if there are many columns. This function is a wrapper of
#' [formatters::paginate_to_mpfs()] and it is mainly meant for exploration and testing.
#'
#' @inheritParams formatters::pag_indices_inner
#' @inheritParams formatters::vert_pag_indices
#' @inheritParams formatters::page_lcpp
#' @inheritParams formatters::toString
#' @param lsting (`listing_df` or `list`)\cr the listing or list of listings to paginate.
#' @param lpp (`numeric(1)` or `NULL`)\cr number of rows/lines (excluding titles and footers)
#'   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 (`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.
#'
#' @examples
#' 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)
#'
#' paginate_listing(lsting, cpp = 100, lpp = 40)
#'
#' paginate_listing(lsting, cpp = 80, lpp = 40, verbose = TRUE)
#'
#' @export
#' @rdname paginate
paginate_listing <- function(lsting,
                             page_type = "letter",
                             font_family = "Courier",
                             font_size = 8,
                             lineheight = 1,
                             landscape = FALSE,
                             pg_width = NULL,
                             pg_height = NULL,
                             margins = c(top = .5, bottom = .5, left = .75, right = .75),
                             lpp = NA_integer_,
                             cpp = NA_integer_,
                             colwidths = NULL,
                             tf_wrap = !is.null(max_width),
                             rep_cols = NULL,
                             max_width = NULL,
                             verbose = FALSE,
                             print_pages = TRUE) {
  checkmate::assert_multi_class(lsting, c("listing_df", "list"))
  checkmate::assert_numeric(colwidths, lower = 0, len = length(listing_dispcols(lsting)), null.ok = TRUE)
  checkmate::assert_flag(tf_wrap)
  checkmate::assert_count(max_width, null.ok = TRUE)
  checkmate::assert_flag(verbose)
  checkmate::assert_flag(print_pages)

  pages <- paginate_to_mpfs(lsting,
    page_type = page_type,
    font_family = font_family,
    font_size = font_size,
    lineheight = lineheight,
    landscape = landscape,
    pg_width = pg_width,
    pg_height = pg_height,
    margins = margins,
    lpp = lpp,
    cpp = cpp,
    colwidths = colwidths,
    tf_wrap = tf_wrap,
    max_width = max_width,
    rep_cols = rep_cols,
    verbose = verbose
  )

  if (print_pages) {
    nothing <- lapply(seq_along(pages), function(pagi) {
      cat("--- Page", paste0(pagi, "/", length(pages)), "---\n")
      # It is NULL because paginate_mpfs takes care of it
      cat(toString(pages[[pagi]], widths = NULL, tf_wrap = tf_wrap, max_width = max_width))
      cat("\n")
    })
  }
  invisible(pages)
}

1		#' Paginate listings
2		#'
3		#' @description `r lifecycle::badge("experimental")`
4		#'
5		#' Pagination of a listing. This can be vertical for long listings with many
6		#' rows and/or horizontal if there are many columns. This function is a wrapper of
7		#' [formatters::paginate_to_mpfs()] and it is mainly meant for exploration and testing.
8		#'
9		#' @inheritParams formatters::pag_indices_inner
10		#' @inheritParams formatters::vert_pag_indices
11		#' @inheritParams formatters::page_lcpp
12		#' @inheritParams formatters::toString
13		#' @param lsting (`listing_df` or `list`)\cr the listing or list of listings to paginate.
14		#' @param lpp (`numeric(1)` or `NULL`)\cr number of rows/lines (excluding titles and footers)
15		#' to include per page. Standard is `70` while `NULL` disables vertical pagination.
16		#' @param cpp (`numeric(1)` or `NULL`)\cr width (in characters) of the pages for horizontal
17		#' pagination. `NULL` (the default) indicates no horizontal pagination should be done.
18		#' @param print_pages (`flag`)\cr whether the paginated listing should be printed to the console
19		#' (`cat(toString(x))`).
20		#'
21		#' @return A list of `listing_df` objects where each list element corresponds to a separate page.
22		#'
23		#' @examples
24		#' dat <- ex_adae
25		#' lsting <- as_listing(dat[1:25, ], disp_cols = c("USUBJID", "AESOC", "RACE", "AETOXGR", "BMRKR1"))
26		#' mat <- matrix_form(lsting)
27		#' cat(toString(mat))
28		#'
29		#' paginate_listing(lsting, lpp = 10)
30		#'
31		#' paginate_listing(lsting, cpp = 100, lpp = 40)
32		#'
33		#' paginate_listing(lsting, cpp = 80, lpp = 40, verbose = TRUE)
34		#'
35		#' @export
36		#' @rdname paginate
37		paginate_listing <- function(lsting,
38		page_type = "letter",
39		font_family = "Courier",
40		font_size = 8,
41		lineheight = 1,
42		landscape = FALSE,
43		pg_width = NULL,
44		pg_height = NULL,
45		margins = c(top = .5, bottom = .5, left = .75, right = .75),
46		lpp = NA_integer_,
47		cpp = NA_integer_,
48		colwidths = NULL,
49		tf_wrap = !is.null(max_width),
50		rep_cols = NULL,
51		max_width = NULL,
52		verbose = FALSE,
53		print_pages = TRUE) {
54	22x	checkmate::assert_multi_class(lsting, c("listing_df", "list"))
55	22x	checkmate::assert_numeric(colwidths, lower = 0, len = length(listing_dispcols(lsting)), null.ok = TRUE)
56	21x	checkmate::assert_flag(tf_wrap)
57	21x	checkmate::assert_count(max_width, null.ok = TRUE)
58	21x	checkmate::assert_flag(verbose)
59	21x	checkmate::assert_flag(print_pages)
60
61	21x	pages <- paginate_to_mpfs(lsting,
62	21x	page_type = page_type,
63	21x	font_family = font_family,
64	21x	font_size = font_size,
65	21x	lineheight = lineheight,
66	21x	landscape = landscape,
67	21x	pg_width = pg_width,
68	21x	pg_height = pg_height,
69	21x	margins = margins,
70	21x	lpp = lpp,
71	21x	cpp = cpp,
72	21x	colwidths = colwidths,
73	21x	tf_wrap = tf_wrap,
74	21x	max_width = max_width,
75	21x	rep_cols = rep_cols,
76	21x	verbose = verbose
77		)
78
79	21x	if (print_pages) {
80	!	nothing <- lapply(seq_along(pages), function(pagi) {
81	!	cat("--- Page", paste0(pagi, "/", length(pages)), "---\n")
82		# It is NULL because paginate_mpfs takes care of it
83	!	cat(toString(pages[[pagi]], widths = NULL, tf_wrap = tf_wrap, max_width = max_width))
84	!	cat("\n")
85		})
86		}
87	21x	invisible(pages)
88		}

1		## #' Print a listing to the terminal
2		## #' @param x listing_df. the listing
3		## #' @param ... ANY. unused
4		## #' @return prints the listing object to the screen and silently returns the object
5		## #' @export
6		## setMethod("print", "listing_df",
7		## function(x, ...) {
8		## cat(toString(listing_matrix_form(x)))
9		## invisible(x)
10		## })
11
12		#' Methods for `listing_df` objects
13		#'
14		#' See core documentation in [`formatters`] for descriptions of these functions.
15		#'
16		#' @inheritParams formatters::toString
17		#' @param x (`listing_df`)\cr the listing.
18		#' @param ... additional parameters passed to [formatters::toString()].
19		#'
20		#' @method print listing_df
21		#'
22		#' @export
23		#' @name listing_methods
24		print.listing_df <- function(x, widths = NULL, tf_wrap = FALSE, max_width = NULL, ...) {
25	!	cat(toString(matrix_form(x), widths = widths, tf_wrap = tf_wrap, max_width = max_width, ...))
26	!	invisible(x)
27		}
28
29		#' @exportMethod toString
30		#' @name listing_methods
31		#' @aliases toString,listing_df-method
32		setMethod("toString", "listing_df", function(x, ...) {
33	4x	toString(matrix_form(x), ...)
34		})
35
36		## because rle in base is too much of a stickler for being atomic
37		basic_run_lens <- function(x) {
38	134x	n <- length(x)
39	134x	if (n == 0) {
40	!	return(integer())
41		}
42
43	134x	y <- x[-1L] != x[-n]
44	134x	i <- c(which(y), n)
45	134x	diff(c(0L, i))
46		}
47
48		#' @param df (`listing_df`)\cr the listing.
49		#' @param colnm (`string`)\cr column name.
50		#' @param colvec (`vector`)\cr column values based on `colnm`.
51		#'
52		#' @rdname vec_nlines
53		#' @keywords internal
54		format_colvector <- function(df, colnm, colvec = df[[colnm]]) {
55	600x	if (missing(colvec) && !(colnm %in% names(df))) {
56	!	stop("column ", colnm, " not found")
57		}
58	600x	na_str <- obj_na_str(colvec)
59	600x	if (is.null(na_str) \|\| all(is.na(na_str))) {
60	!	na_str <- rep("-", max(1L, length(na_str)))
61		}
62
63	600x	strvec <- vapply(colvec, format_value, "", format = obj_format(colvec), na_str = na_str)
64	600x	strvec
65		}
66
67		#' Utilities for formatting a listing column
68		#'
69		#' For `vec_nlines`, calculate the number of lines each element of a column vector will
70		#' take to render. For `format_colvector`,
71		#'
72		#' @param vec (`vector`)\cr a column vector to be rendered into ASCII.
73		#' @param max_width (`numeric(1)` or `NULL`)\cr the width to render the column with.
74		#' @return (`numeric`)\cr a vector of the number of lines element-wise that will be
75		#' needed to render the elements of `vec` to width `max_width`.
76		#'
77		#' @keywords internal
78	600x	setGeneric("vec_nlines", function(vec, max_width = NULL) standardGeneric("vec_nlines"))
79
80		#' @param vec (`vector`)\cr a vector.
81		#'
82		#' @rdname vec_nlines
83		#' @keywords internal
84		setMethod("vec_nlines", "ANY", function(vec, max_width = NULL) {
85	600x	if (is.null(max_width)) {
86	600x	max_width <- floor(0.9 * getOption("width")) # default of base::strwrap
87		# NB: flooring as it is used as <= (also in base::strwrap)
88		}
89		# in formatters for characters
90	600x	unlist(lapply(format_colvector(colvec = vec), nlines, max_width = max_width))
91		})
92
93		## setMethod("vec_nlines", "character", function(vec, max_width = NULL) {
94		## strvec <- wrap_txt(format_colvector(colvec = vec), width = max_width, collapse = "\n")
95		## mtchs <- gregexpr("\n", strvec, fixed = TRUE)
96		## 1L + vapply(mtchs, function(vi) sum(vi > 0), 1L)
97		## })
98
99		## setMethod("vec_nlines", "factor", function(vec, max_width = NULL) {
100		## lvl_nlines <- vec_nlines(levels(vec), max_width = max_width)
101		## ret <- lvl_nlines[vec]
102		## ret[is.na(ret)] <- format_value(NA_character
103		## })
104
105		#' Make pagination data frame for a listing
106		#'
107		#' @inheritParams formatters::make_row_df
108		#' @param tt (`listing_df`)\cr the listing to be rendered.
109		#' @param visible_only (`flag`)\cr ignored, as listings do not have
110		#' non-visible structural elements.
111		#'
112		#' @return a `data.frame` with pagination information.
113		#'
114		#' @seealso [formatters::make_row_df()]
115		#'
116		#' @examples
117		#' lsting <- as_listing(mtcars)
118		#' mf <- matrix_form(lsting)
119		#'
120		#' @export
121		setMethod(
122		"make_row_df", "listing_df",
123		function(tt, colwidths = NULL, visible_only = TRUE,
124		rownum = 0,
125		indent = 0L,
126		path = character(),
127		incontent = FALSE,
128		repr_ext = 0L,
129		repr_inds = integer(),
130		sibpos = NA_integer_,
131		nsibs = NA_integer_) {
132		## assume sortedness by keycols
133	135x	keycols <- get_keycols(tt)
134	135x	dispcols <- listing_dispcols(tt)
135	135x	abs_rownumber <- seq_along(tt[[1]])
136	135x	if (length(keycols) >= 1) {
137	134x	runlens <- basic_run_lens(tt[[tail(keycols, 1)]])
138		} else {
139	1x	runlens <- rep(1, NROW(tt))
140		}
141	135x	sibpos <- unlist(lapply(runlens, seq_len))
142	135x	nsibs <- rep(runlens, times = runlens)
143	135x	extents <- rep(1L, nrow(tt))
144	135x	if (length(colwidths) > 0 && length(colwidths) != length(dispcols)) {
145	!	stop(
146	!	"Non-null colwidths vector must be the same length as the number of display columns.\n",
147	!	"Got: ", length(colwidths), "(", length(dispcols), " disp cols)."
148		)
149		}
150	135x	if (length(colwidths) > 0) {
151	!	names(colwidths) <- dispcols
152		}
153		## extents is a row-wise vector of extents, for each col, we update
154		## if that column has any rows wider than the previously recorded extent.
155	135x	for (col in dispcols) {
156		## duplicated from matrix_form method, refactor!
157	600x	col_ext <- vec_nlines(tt[[col]], max_width = colwidths[col])
158	600x	extents <- ifelse(col_ext > extents, col_ext, extents)
159		}
160	135x	ret <- data.frame(
161	135x	label = "", name = "",
162	135x	abs_rownumber = abs_rownumber,
163	135x	path = I(as.list(rep(NA_character_, NROW(tt)))),
164	135x	pos_in_siblings = sibpos,
165	135x	n_siblings = nsibs,
166	135x	self_extent = extents,
167	135x	par_extent = 0L,
168	135x	reprint_inds = I(replicate(NROW(tt), list(integer()))),
169	135x	node_class = "listing_df",
170	135x	indent = 0L,
171	135x	nrowrefs = 0L, ## XXX this doesn't support footnotes
172	135x	ncellrefs = 0L, ## XXX this doesn't support footnotes
173	135x	nreflines = 0L, ## XXX this doesn't support footnotes
174	135x	force_page = FALSE,
175	135x	page_title = NA_character_,
176	135x	trailing_sep = NA_character_
177		)
178	135x	stopifnot(identical(
179	135x	names(ret),
180	135x	names(pagdfrow(
181	135x	nm = "", lab = "", rnum = 1L, pth = NA_character_, extent = 1L,
182	135x	rclass = ""
183		))
184		))
185	135x	ret
186		}
187		)
188
189		## tt$sibpos <- unlist(lapply(
190		## ## don't support pathing for now
191		## tt$path <- I(lapply(1:NROW(tt),
192		## function(i) {
193		## retpath <- character(2*length(keycols))
194		## for(j in seq_along(keycols)) {
195		## retpath[2*j - 1] <- keycols[j]
196		## retpath[2*j] <- tt[i, keycols[j], drop = TRUE]
197		## }
198		## retpath
199		## }))
200		## spl <- split(tt, tt[keycols])
201		## spl <- spl[vapply(spl, function(y) NROW(y) > 0, NA)]
202		## dfs <- lapply(spl, function(df) {
203		## df <- df[order(df$abs_rownumber),]
204		## ndf <- NROW(df)
205		## lapply(1:ndf, function(i) {
206		## rw <- df[i,]
207		## stopifnot(nrow(rw) == 1)
208		## pagdfrow(nm = "",
209		## lab = "",
210		## rnum = rw$abs_rownumber,
211		## pth = NA_character_,
212		## sibpos = i,
213		## nsibs = ndf,
214		## extent = 1L,
215		## rclass = "listing_df",
216		## repind = integer())
217		## })
218		## })
219		## ret <- do.call(rbind, unlist(dfs, recursive = FALSE))
220		## ret <- ret[order(ret$abs_rownumber),]
221		## ret
222		## })
223
224		#' @inheritParams base::Extract
225		#' @param x (`listing_df`)\cr the listing.
226		#' @param i (`any`)\cr object passed to base `[` methods.
227		#' @param j (`any`)\cr object passed to base `[` methods.
228		#'
229		#' @export
230		#' @aliases [,listing_df-method
231		#' @rdname listing_methods
232		setMethod(
233		"[", "listing_df",
234		function(x, i, j, drop = FALSE) {
235	!	xattr <- attributes(x)
236	!	xattr$names <- xattr$names[j]
237	!	res <- NextMethod()
238	!	if (!drop) {
239	!	attributes(res) <- xattr
240		}
241	!	res
242		}
243		)
244
245		#' @rdname listing_methods
246		#' @param obj (`listing_df`)\cr the listing.
247		#'
248		#' @return
249		#' * Accessor methods return the value of the aspect of `obj`.
250		#' * Setter methods return `obj` with the relevant element of the listing updated.
251		#'
252		#' @examples
253		#' lsting <- as_listing(mtcars)
254		#' main_title(lsting) <- "Hi there"
255		#'
256		#' main_title(lsting)
257		#'
258		#' @export
259		setMethod(
260		"main_title", "listing_df",
261	137x	function(obj) attr(obj, "main_title") %\|\|% character()
262		)
263
264		#' @rdname listing_methods
265		#' @export
266		setMethod(
267		"subtitles", "listing_df",
268	147x	function(obj) attr(obj, "subtitles") %\|\|% character()
269		)
270
271		#' @rdname listing_methods
272		#' @export
273		setMethod(
274		"main_footer", "listing_df",
275	136x	function(obj) attr(obj, "main_footer") %\|\|% character()
276		)
277
278		#' @rdname listing_methods
279		#' @export
280		setMethod(
281		"prov_footer", "listing_df",
282	136x	function(obj) attr(obj, "prov_footer") %\|\|% character()
283		)
284
285		.chk_value <- function(val, fname, len_one = FALSE, null_ok = TRUE) {
286	222x	if (null_ok && is.null(val)) {
287	178x	return(TRUE)
288		}
289	44x	if (!is.character(val)) {
290	4x	stop("value for ", fname, " must be a character, got ",
291	4x	"object of class: ", paste(class(val), collapse = ","),
292	4x	call. = FALSE
293		)
294		}
295	40x	if (len_one && length(val) > 1) {
296	1x	stop(
297	1x	"value for ", fname, " must be length <= 1, got ",
298	1x	"vector of length ", length(val)
299		)
300		}
301	39x	TRUE
302		}
303
304		#' @rdname listing_methods
305		#' @export
306		setMethod(
307		"main_title<-", "listing_df",
308		function(obj, value) {
309		## length 1 restriction is to match rtables behavior
310		## which currently enforces this (though incompletely)
311	55x	.chk_value(value, "main_title", len_one = TRUE)
312	53x	attr(obj, "main_title") <- value
313	53x	obj
314		}
315		)
316
317		#' @rdname listing_methods
318		#' @export
319		setMethod(
320		"subtitles<-", "listing_df",
321		function(obj, value) {
322	62x	.chk_value(value, "subtitles")
323	61x	attr(obj, "subtitles") <- value
324	61x	obj
325		}
326		)
327
328		#' @rdname listing_methods
329		#' @export
330		setMethod(
331		"main_footer<-", "listing_df",
332		function(obj, value) {
333	53x	.chk_value(value, "main_footer")
334	52x	attr(obj, "main_footer") <- value
335	52x	obj
336		}
337		)
338
339		#' @rdname listing_methods
340		#' @export
341		setMethod(
342		"prov_footer<-", "listing_df",
343		function(obj, value) {
344	52x	.chk_value(value, "prov_footer")
345	51x	attr(obj, "prov_footer") <- value
346	51x	obj
347		}
348		)
349
350		#' @rdname listing_methods
351		#' @export
352		setMethod(
353		"num_rep_cols", "listing_df",
354		function(obj) {
355	35x	length(get_keycols(obj))
356		}
357		)

1		setOldClass(c("listing_df", "tbl_df", "tbl", "data.frame"))
2		setOldClass(c("MatrixPrintForm", "list"))
3
4		#' Create a listing from a `data.frame` or `tibble`
5		#'
6		#' @description `r lifecycle::badge("experimental")`
7		#'
8		#' Create listings displaying `key_cols` and `disp_cols` to produce a compact and
9		#' elegant representation of the input `data.frame` or `tibble`.
10		#'
11		#' @param df (`data.frame` or `listing_df`)\cr the `data.frame` to be converted to a listing or
12		#' `listing_df` to be modified.
13		#' @param key_cols (`character`)\cr vector of names of columns which should be treated as key columns
14		#' when rendering the listing. Key columns allow you to group repeat occurrences.
15		#' @param disp_cols (`character` or `NULL`)\cr vector of names of non-key columns which should be
16		#' displayed when the listing is rendered. Defaults to all columns of `df` not named in `key_cols` or
17		#' `non_disp_cols`.
18		#' @param non_disp_cols (`character` or `NULL`)\cr vector of names of non-key columns to be excluded as display
19		#' columns. All other non-key columns are treated as display columns. Ignored if `disp_cols` is non-`NULL`.
20		#' @param unique_rows (`flag`)\cr whether only unique rows should be included in the listing. Defaults to `FALSE`.
21		#' @param default_formatting (`list`)\cr a named list of default column format configurations to apply when rendering
22		#' the listing. Each name-value pair consists of a name corresponding to a data class (or "numeric" for all
23		#' unspecified numeric classes) and a value of type `fmt_config` with the format configuration that should be
24		#' implemented for columns of that class. If named element "all" is included in the list, this configuration will be
25		#' used for all data classes not specified. Objects of type `fmt_config` can take 3 arguments: `format`, `na_str`,
26		#' and `align`.
27		#' @param col_formatting (`list`)\cr a named list of custom column formatting configurations to apply to specific
28		#' columns when rendering the listing. Each name-value pair consists of a name corresponding to a column name and a
29		#' value of type `fmt_config` with the formatting configuration that should be implemented for that column. Objects
30		#' of type `fmt_config` can take 3 arguments: `format`, `na_str`, and `align`. Defaults to `NULL`.
31		#' @param main_title (`string` or `NULL`)\cr the main title for the listing, or `NULL` (the default).
32		#' @param subtitles (`character` or `NULL`)\cr a vector of subtitles for the listing, or `NULL` (the default).
33		#' @param main_footer (`character` or `NULL`)\cr a vector of main footer lines for the listing, or `NULL` (the default).
34		#' @param prov_footer (`character` or `NULL`)\cr a vector of provenance footer lines for the listing, or `NULL`
35		#' (the default). Each string element is placed on a new line.
36		#' @param split_into_pages_by_var (`character` or `NULL`)\cr the name of a variable for on the listing should be split
37		#' into pages, with each page corresponding to one unique value/level of the variable. See
38		#' [split_into_pages_by_var()] for more details.
39		#' @param vec (`string`)\cr name of a column vector from a `listing_df` object to be annotated as a key column.
40		#'
41		#' @return A `listing_df` object, sorted by its key columns.
42		#'
43		#' @details
44		#' At its core, a `listing_df` object is a `tbl_df` object with a customized
45		#' print method and support for the formatting and pagination machinery provided by
46		#' the `formatters` package.
47		#'
48		#' `listing_df` objects have two 'special' types of columns: key columns and display columns.
49		#'
50		#' Key columns act as indexes, which means a number of things in practice.
51		#'
52		#' All key columns are also display columns.
53		#'
54		#' `listing_df` objects are always sorted by their set of key columns at creation time.
55		#' Any `listing_df` object which is not sorted by its full set of key columns (e.g.,
56		#' one whose rows have been reordered explicitly during creation) is invalid and the behavior
57		#' when rendering or paginating that object is undefined.
58		#'
59		#' Each value of a key column is printed only once per page and per unique combination of
60		#' values for all higher-priority (i.e., to the left of it) key columns. Locations
61		#' where a repeated value would have been printed within a key column for the same
62		#' higher-priority-key combination on the same page are rendered as empty space.
63		#' Note, determination of which elements to display within a key column at rendering is
64		#' based on the underlying value; any non-default formatting applied to the column
65		#' has no effect on this behavior.
66		#'
67		#' Display columns are columns which should be rendered, but are not key columns. By
68		#' default this is all non-key columns in the incoming data, but in need not be.
69		#' Columns in the underlying data which are neither key nor display columns remain
70		#' within the object available for computations but *are not rendered during
71		#' printing or export of the listing*.
72		#'
73		#' @examples
74		#' dat <- ex_adae
75		#'
76		#' # This example demonstrates the listing with key_cols (values are grouped by USUBJID) and
77		#' # multiple lines in prov_footer
78		#' lsting <- as_listing(dat[1:25, ],
79		#' key_cols = c("USUBJID", "AESOC"),
80		#' main_title = "Example Title for Listing",
81		#' subtitles = "This is the subtitle for this Adverse Events Table",
82		#' main_footer = "Main footer for the listing",
83		#' prov_footer = c(
84		#' "You can even add a subfooter", "Second element is place on a new line",
85		#' "Third string"
86		#' )
87		#' ) %>%
88		#' add_listing_col("AETOXGR") %>%
89		#' add_listing_col("BMRKR1", format = "xx.x") %>%
90		#' add_listing_col("AESER / AREL", fun = function(df) paste(df$AESER, df$AREL, sep = " / "))
91		#'
92		#' mat <- matrix_form(lsting)
93		#'
94		#' cat(toString(mat))
95		#'
96		#' # This example demonstrates the listing table without key_cols
97		#' # and specifying the cols with disp_cols.
98		#' dat <- ex_adae
99		#' lsting <- as_listing(dat[1:25, ],
100		#' disp_cols = c("USUBJID", "AESOC", "RACE", "AETOXGR", "BMRKR1")
101		#' )
102		#'
103		#' mat <- matrix_form(lsting)
104		#'
105		#' cat(toString(mat))
106		#'
107		#' # This example demonstrates a listing with format configurations specified
108		#' # via the default_formatting and col_formatting arguments
109		#' dat <- ex_adae
110		#' dat$AENDY[3:6] <- NA
111		#' lsting <- as_listing(dat[1:25, ],
112		#' key_cols = c("USUBJID", "AESOC"),
113		#' disp_cols = c("STUDYID", "SEX", "ASEQ", "RANDDT", "ASTDY", "AENDY"),
114		#' default_formatting = list(
115		#' all = fmt_config(align = "left"),
116		#' numeric = fmt_config(
117		#' format = "xx.xx",
118		#' na_str = "<No data>",
119		#' align = "right"
120		#' )
121		#' )
122		#' ) %>%
123		#' add_listing_col("BMRKR1", format = "xx.x", align = "center")
124		#'
125		#' mat <- matrix_form(lsting)
126		#'
127		#' cat(toString(mat))
128		#'
129		#' @export
130		#' @rdname listings
131		as_listing <- function(df,
132		key_cols = names(df)[1],
133		disp_cols = NULL,
134		non_disp_cols = NULL,
135		unique_rows = FALSE,
136		default_formatting = list(all = fmt_config()),
137		col_formatting = NULL,
138		main_title = NULL,
139		subtitles = NULL,
140		main_footer = NULL,
141		prov_footer = NULL,
142		split_into_pages_by_var = NULL) {
143	51x	if (length(non_disp_cols) > 0 && length(intersect(key_cols, non_disp_cols)) > 0) {
144	1x	stop(
145	1x	"Key column also listed in non_disp_cols. All key columns are by",
146	1x	" definition display columns."
147		)
148		}
149	50x	if (!is.null(disp_cols) && !is.null(non_disp_cols)) {
150	1x	stop("Got non-null values for both disp_cols and non_disp_cols. This is not supported.")
151	49x	} else if (is.null(disp_cols)) {
152		## non_disp_cols NULL is ok here
153	19x	cols <- setdiff(names(df), c(key_cols, non_disp_cols))
154		} else {
155		## disp_cols non-null, non_disp_cols NULL
156	30x	cols <- disp_cols
157		}
158	49x	if (!all(sapply(default_formatting, is, class2 = "fmt_config"))) {
159	!	stop(
160	!	"All format configurations supplied in `default_formatting`",
161	!	" must be of type `fmt_config`."
162		)
163		}
164	49x	if (!(is.null(col_formatting) \|\| all(sapply(col_formatting, is, class2 = "fmt_config")))) {
165	!	stop(
166	!	"All format configurations supplied in `col_formatting`",
167	!	" must be of type `fmt_config`."
168		)
169		}
170
171	49x	df <- as_tibble(df)
172	49x	varlabs <- var_labels(df, fill = TRUE)
173	49x	o <- do.call(order, df[key_cols])
174	49x	if (is.unsorted(o)) {
175	25x	if (interactive()) {
176	!	message("sorting incoming data by key columns")
177		}
178	25x	df <- df[o, ]
179		}
180
181		## reorder the full set of cols to ensure key columns are first
182	49x	ordercols <- c(key_cols, setdiff(names(df), key_cols))
183	49x	df <- df[, ordercols]
184	49x	var_labels(df) <- varlabs[ordercols]
185
186	49x	for (cnm in key_cols) {
187	77x	df[[cnm]] <- as_keycol(df[[cnm]])
188		}
189
190		## key cols must be leftmost cols
191	49x	cols <- c(key_cols, setdiff(cols, key_cols))
192
193	49x	row_all_na <- apply(df[cols], 1, function(x) all(is.na(x)))
194	49x	if (any(row_all_na)) {
195	1x	warning("rows that only contain NA values have been trimmed")
196	1x	df <- df[!row_all_na, ]
197		}
198
199		# set col format configs
200	49x	df[cols] <- lapply(cols, function(col) {
201	272x	col_class <- tail(class(df[[col]]), 1)
202	272x	col_fmt_class <- if (!col_class %in% names(default_formatting) && is.numeric(df[[col]])) "numeric" else col_class
203	272x	col_fmt <- if (col %in% names(col_formatting)) {
204	6x	col_formatting[[col]]
205	272x	} else if (col_fmt_class %in% names(default_formatting)) {
206	6x	default_formatting[[col_fmt_class]]
207		} else {
208	260x	if (!"all" %in% names(default_formatting)) {
209	!	stop(
210	!	"Format configurations must be supplied for all listing columns. ",
211	!	"To cover all remaining columns please add an 'all' configuration",
212	!	" to `default_formatting`."
213		)
214		}
215	260x	default_formatting[["all"]]
216		}
217		# ANY attr <- fmt_config slot
218	272x	obj_format(df[[col]]) <- obj_format(col_fmt)
219	272x	obj_na_str(df[[col]]) <- if (is.null(obj_na_str(col_fmt))) "NA" else obj_na_str(col_fmt)
220	272x	obj_align(df[[col]]) <- if (is.null(obj_align(col_fmt))) "left" else obj_align(col_fmt)
221	272x	df[[col]]
222		})
223
224	2x	if (unique_rows) df <- df[!duplicated(df[, cols]), ]
225
226	49x	class(df) <- c("listing_df", class(df))
227
228		## these all work even when the value is NULL
229	49x	main_title(df) <- main_title
230	49x	main_footer(df) <- main_footer
231	49x	subtitles(df) <- subtitles
232	49x	prov_footer(df) <- prov_footer
233	49x	listing_dispcols(df) <- cols
234
235	49x	if (!is.null(split_into_pages_by_var)) {
236	1x	df <- split_into_pages_by_var(df, split_into_pages_by_var)
237		}
238
239	49x	df
240		}
241
242		#' @export
243		#' @rdname listings
244		as_keycol <- function(vec) {
245	77x	if (is.factor(vec)) {
246	13x	lab <- obj_label(vec)
247	13x	vec <- as.character(vec)
248	13x	obj_label(vec) <- lab
249		}
250	77x	class(vec) <- c("listing_keycol", class(vec))
251	77x	vec
252		}
253
254		#' @export
255		#' @rdname listings
256		is_keycol <- function(vec) {
257	5694x	inherits(vec, "listing_keycol")
258		}
259
260		#' @export
261		#' @rdname listings
262		get_keycols <- function(df) {
263	305x	names(which(sapply(df, is_keycol)))
264		}
265
266		#' @inherit formatters::matrix_form
267		#' @param indent_rownames (`flag`)\cr silently ignored, as listings do not have row names
268		#' nor indenting structure.
269		#' @param expand_newlines (`flag`)\cr this should always be `TRUE` for listings. We keep it
270		#' for debugging reasons.
271		#'
272		#' @return a [`MatrixPrintForm`] object.
273		#'
274		#' @seealso [formatters::matrix_form()]
275		#'
276		#' @examples
277		#' lsting <- as_listing(mtcars)
278		#' mf <- matrix_form(lsting)
279		#'
280		#' @export
281		setMethod(
282		"matrix_form", "listing_df",
283		rix_form <- function(obj, indent_rownames = FALSE, expand_newlines = TRUE) {
284		## we intentionally silently ignore indent_rownames because listings have
285		## no rownames, but formatters::vert_pag_indices calls matrix_form(obj, TRUE)
286		## unconditionally.
287	134x	cols <- attr(obj, "listing_dispcols")
288	134x	listing <- obj[, cols]
289	134x	atts <- attributes(obj)
290	134x	atts$names <- cols
291	134x	attributes(listing) <- atts
292	134x	keycols <- get_keycols(listing)
293
294	134x	bodymat <- matrix("",
295	134x	nrow = nrow(listing),
296	134x	ncol = ncol(listing)
297		)
298
299	134x	colnames(bodymat) <- names(listing)
300
301	134x	curkey <- ""
302	134x	for (i in seq_along(keycols)) {
303	196x	kcol <- keycols[i]
304	196x	kcolvec <- listing[[kcol]]
305	196x	kcolvec <- vapply(kcolvec, format_value, "", format = obj_format(kcolvec), na_str = obj_na_str(kcolvec))
306	196x	curkey <- paste0(curkey, kcolvec)
307	196x	disp <- c(TRUE, tail(curkey, -1) != head(curkey, -1))
308	196x	bodymat[disp, kcol] <- kcolvec[disp]
309		}
310
311	134x	nonkeycols <- setdiff(names(listing), keycols)
312	134x	if (length(nonkeycols) > 0) {
313	133x	for (nonk in nonkeycols) {
314	402x	vec <- listing[[nonk]]
315	402x	vec <- vapply(vec, format_value, "", format = obj_format(vec), na_str = obj_na_str(vec))
316	402x	bodymat[, nonk] <- vec
317		}
318		}
319
320	134x	fullmat <- rbind(
321	134x	var_labels(listing, fill = TRUE),
322	134x	bodymat
323		)
324
325	134x	colaligns <- rbind(
326	134x	rep("center", length(cols)),
327	134x	matrix(sapply(listing, obj_align),
328	134x	ncol = length(cols),
329	134x	nrow = nrow(fullmat) - 1,
330	134x	byrow = TRUE
331		)
332		)
333
334	134x	MatrixPrintForm(
335	134x	strings = fullmat,
336	134x	spans = matrix(1,
337	134x	nrow = nrow(fullmat),
338	134x	ncol = ncol(fullmat)
339		),
340	134x	ref_fnotes = list(),
341	134x	aligns = colaligns,
342	134x	formats = matrix(1,
343	134x	nrow = nrow(fullmat),
344	134x	ncol = ncol(fullmat)
345		),
346	134x	row_info = make_row_df(obj),
347	134x	listing_keycols = keycols, # It is always something
348	134x	nlines_header = 1, # We allow only one level of headers and nl expansion happens after
349	134x	nrow_header = 1,
350	134x	has_topleft = FALSE,
351	134x	has_rowlabs = FALSE,
352	134x	expand_newlines = expand_newlines,
353	134x	main_title = main_title(obj),
354	134x	subtitles = subtitles(obj),
355	134x	page_titles = page_titles(obj),
356	134x	main_footer = main_footer(obj),
357	134x	prov_footer = prov_footer(obj)
358		)
359		}
360		)
361
362		#' @export
363		#' @rdname listings
364	179x	listing_dispcols <- function(df) attr(df, "listing_dispcols") %\|\|% character()
365
366		#' @param new (`character`)\cr vector of names of columns to be added to
367		#' the set of display columns.
368		#'
369		#' @export
370		#' @rdname listings
371		add_listing_dispcol <- function(df, new) {
372	20x	listing_dispcols(df) <- c(listing_dispcols(df), new)
373	20x	df
374		}
375
376		#' @param value (`string`)\cr new value.
377		#'
378		#' @export
379		#' @rdname listings
380		`listing_dispcols<-` <- function(df, value) {
381	69x	if (!is.character(value)) {
382	!	stop(
383	!	"dispcols must be a character vector of column names, got ",
384	!	"object of class: ", paste(class(value), collapse = ",")
385		)
386		}
387	69x	chk <- setdiff(value, names(df)) ## remember setdiff is not symmetrical
388	69x	if (length(chk) > 0) {
389	!	stop(
390	!	"listing display columns must be columns in the underlying data. ",
391	!	"Column(s) ", paste(chk, collapse = ", "), " not present in the data."
392		)
393		}
394	69x	attr(df, "listing_dispcols") <- unique(value)
395	69x	df
396		}
397
398		#' @inheritParams formatters::fmt_config
399		#' @param name (`string`)\cr name of the existing or new column to be
400		#' displayed when the listing is rendered.
401		#' @param fun (`function` or `NULL`)\cr a function which accepts `df` and
402		#' returns the vector for a new column, which is added to `df` as
403		#' `name`, or `NULL` if marking an existing column as a listing column.
404		#'
405		#' @return `df` with `name` created (if necessary) and marked for
406		#' display during rendering.
407		#'
408		#' @export
409		#' @rdname listings
410		add_listing_col <- function(df,
411		name,
412		fun = NULL,
413		format = NULL,
414		na_str = "NA",
415		align = "left") {
416	20x	if (!is.null(fun)) {
417	1x	vec <- with_label(fun(df), name)
418	19x	} else if (name %in% names(df)) {
419	19x	vec <- df[[name]]
420		} else {
421	!	stop(
422	!	"Column '", name, "' not found. name argument must specify an existing column when ",
423	!	"no generating function (fun argument) is specified."
424		)
425		}
426
427	20x	if (!is.null(format)) {
428	10x	obj_format(vec) <- format
429		}
430
431	20x	obj_na_str(vec) <- na_str
432	20x	obj_align(vec) <- align
433
434		## this works for both new and existing columns
435	20x	df[[name]] <- vec
436	20x	df <- add_listing_dispcol(df, name)
437	20x	df
438		}
439
440		#' Split Listing by Values of a Variable
441		#'
442		#' @description `r lifecycle::badge("experimental")`
443		#'
444		#' Split is performed based on unique values of the given parameter present in the listing.
445		#' Each listing can only be split by variable once. If this function is applied prior to
446		#' pagination, parameter values will be separated by page.
447		#'
448		#' @param lsting listing_df. The listing to split.
449		#' @param var character. Name of the variable to split on.
450		#' @param page_prefix character. Prefix to be appended with the split value (`var` level),
451		#' at the end of the subtitles, corresponding to each resulting list element (listing).
452		#'
453		#' @return A list of `lsting_df` objects each corresponding to a unique value of `var`.
454		#'
455		#' @note This function should only be used after the complete listing has been created. The
456		#' listing cannot be modified further after applying this function.
457		#'
458		#' @examples
459		#' dat <- ex_adae[1:20, ]
460		#'
461		#' lsting <- as_listing(
462		#' dat,
463		#' key_cols = c("USUBJID", "AGE"),
464		#' disp_cols = "SEX",
465		#' main_title = "title",
466		#' main_footer = "footer"
467		#' ) %>%
468		#' add_listing_col("BMRKR1", format = "xx.x") %>%
469		#' split_into_pages_by_var("SEX")
470		#'
471		#' lsting
472		#'
473		#' @export
474		split_into_pages_by_var <- function(lsting, var, page_prefix = var) {
475	5x	checkmate::assert_class(lsting, "listing_df")
476	5x	checkmate::assert_choice(var, names(lsting))
477
478	5x	lsting_by_var <- list()
479	5x	for (lvl in unique(lsting[[var]])) {
480	10x	var_desc <- paste0(page_prefix, ": ", lvl)
481	10x	lsting_by_var[[lvl]] <- lsting[lsting[[var]] == lvl, ]
482	10x	subtitles(lsting_by_var[[lvl]]) <- c(subtitles(lsting), var_desc)
483		}
484
485	5x	lsting_by_var
486		}