diff --git a/.Rbuildignore b/.Rbuildignore index a0d2b8fc5..f8bf40c4b 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -29,10 +29,6 @@ ~$ ^vignettes/dev-guide$ pkgdown -inst/extdata/Advanced_rtables_part1.pdf -inst/extdata/Advances_rtables_part2.pdf -inst/extdata/Clinical_Trial_Reporting_Tables_in_R.pdf -inst/extdata/r_adoption_slides.pdf -inst/cheatsheet/Cheatsheet_v1-rtables.pdf -inst/cheatsheet/Cheatsheet_v1-rtables.pptx +^inst/extdata$ +^inst/cheatsheet$ ^pkgdown$ diff --git a/DESCRIPTION b/DESCRIPTION index 7dc49c283..5195fa7b6 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -44,6 +44,7 @@ Suggests: dplyr (>= 1.0.5), flextable (>= 0.8.4), knitr (>= 1.42), + lifecycle (>= 0.2.0), officer (>= 0.5.0), r2rtf (>= 0.3.2), rmarkdown (>= 2.19), @@ -58,9 +59,9 @@ VignetteBuilder: Config/Needs/verdepcheck: insightsengineering/formatters, tidyverse/magrittr, mllg/checkmate, rstudio/htmltools, gagolews/stringi, tidymodels/broom, cran/car, tidyverse/dplyr, - davidgohel/flextable, yihui/knitr, davidgohel/officer, Merck/r2rtf, - rstudio/rmarkdown, r-lib/testthat, tidyverse/tibble, tidyverse/tidyr, r-lib/withr, - r-lib/xml2 + davidgohel/flextable, yihui/knitr, r-lib/lifecycle, davidgohel/officer, + Merck/r2rtf, rstudio/rmarkdown, r-lib/testthat, tidyverse/tibble, + tidyverse/tidyr, r-lib/withr, r-lib/xml2 Encoding: UTF-8 Language: en-US LazyData: true @@ -74,7 +75,6 @@ Collate: 'utils.R' 'colby_constructors.R' 'compare_rtables.R' - 'deprecated.R' 'format_rcell.R' 'indent.R' 'make_subset_expr.R' @@ -82,6 +82,7 @@ Collate: 'split_funs.R' 'make_split_fun.R' 'summary.R' + 'package.R' 'tree_accessors.R' 'tt_afun_utils.R' 'tt_compare_tables.R' diff --git a/NAMESPACE b/NAMESPACE index a67d8ac45..b207dee29 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -168,7 +168,6 @@ export(split_rows_by_multivar) export(split_rows_by_quartiles) export(str) export(summarize_row_groups) -export(summarize_rows) export(table_shell) export(table_shell_str) export(table_structure) @@ -181,7 +180,6 @@ export(trim_levels_in_facets) export(trim_levels_in_group) export(trim_levels_to_map) export(trim_rows) -export(trim_zero_rows) export(tt_at_path) export(tt_to_flextable) export(update_ref_indexing) diff --git a/NEWS.md b/NEWS.md index 75553504a..d3c8465ec 100644 --- a/NEWS.md +++ b/NEWS.md @@ -11,6 +11,9 @@ * Fixed `sort_at_path` pathing to ignore leading `"root"` element (regardless of actual root element name) to match current `tt_at_path` behavior. * Fixed `section_div` for analysis of multiple variables (`AnalyzeMultiVars`). +### Miscellaneous +* Removed deprecated functions `add_analyzed_var` and `trim_zero_rows`. + ## rtables 0.6.6 ### New Features * Removed `ref_group` reordering in column splits so not to change the order. diff --git a/R/00tabletrees.R b/R/00tabletrees.R index 40e0ef901..d80ad5421 100644 --- a/R/00tabletrees.R +++ b/R/00tabletrees.R @@ -7,7 +7,6 @@ ## multicolumn: each child analyzes a different column ## arbitrary: children are not related to each other in any systematic fashion. - ## null is ok here. check_ok_label <- function(lbl, multi_ok = FALSE) { if (length(lbl) == 0) { @@ -42,19 +41,12 @@ valid_lbl_pos <- c("default", "visible", "hidden", "topleft") ret } - setOldClass("expression") setClassUnion("SubsetDef", c("expression", "logical", "integer", "numeric")) - - setClassUnion("integerOrNULL", c("NULL", "integer")) setClassUnion("characterOrNULL", c("NULL", "character")) - - - - ## should XXX [splits, s_values, sval_labels, subset(?)] be a data.frame? setClass("TreePos", representation( splits = "list", @@ -68,8 +60,6 @@ validity = function(object) { } ) - - setClassUnion("functionOrNULL", c("NULL", "function")) setClassUnion("listOrNULL", c("NULL", "list")) ## TODO (?) make "list" more specific, e.g FormatList, or FunctionList? @@ -127,7 +117,6 @@ LevelComboSplitValue <- function(val, extr, combolevels, label = val) { ) } - setClass("Split", contains = "VIRTUAL", representation( @@ -154,15 +143,14 @@ setClass("Split", ) ) - setClass("CustomizableSplit", contains = "Split", representation(split_fun = "functionOrNULL") ) +#' @author Gabriel Becker #' @exportClass VarLevelSplit #' @rdname VarLevelSplit -#' @author Gabriel Becker setClass("VarLevelSplit", contains = "CustomizableSplit", representation( @@ -173,8 +161,10 @@ setClass("VarLevelSplit", #' Split on levels within a variable #' #' @inheritParams lyt_args -#' @return a \code{VarLevelSplit} object. #' @inheritParams constr_args +#' +#' @return a `VarLevelSplit` object. +#' #' @export VarLevelSplit <- function(var, split_label, @@ -225,7 +215,6 @@ VarLevelSplit <- function(var, ) } - setClass("AllSplit", contains = "Split") AllSplit <- function(split_label = "", @@ -302,10 +291,11 @@ setClass("ManualSplit", #' @inheritParams lyt_args #' @inheritParams constr_args #' @inheritParams gen_args -#' @param levels character. Levels of the split (i.e. the children of the manual -#' split) +#' @param levels (`character`)\cr levels of the split (i.e. the children of the manual split). +#' +#' @return A `ManualSplit` object. +#' #' @author Gabriel Becker -#' @return A \code{ManualSplit} object. #' @export ManualSplit <- function(levels, label, name = "manual", extra_args = list(), @@ -335,7 +325,6 @@ ManualSplit <- function(levels, label, name = "manual", ) } - ## splits across which variables are being analynzed setClass("MultiVarSplit", contains = "CustomizableSplit", ## "Split", @@ -350,7 +339,6 @@ setClass("MultiVarSplit", } ) - .make_suffix_vec <- function(n) { c( "", @@ -377,12 +365,15 @@ setClass("MultiVarSplit", } ret } + #' Split between two or more different variables #' #' @inheritParams lyt_args #' @inheritParams constr_args +#' +#' @return A `MultiVarSplit` object. +#' #' @author Gabriel Becker -#' @return A \code{MultiVarSplit} object. #' @export MultiVarSplit <- function(vars, split_label = "", @@ -440,12 +431,13 @@ MultiVarSplit <- function(vars, ) } - #' Splits for cutting by values of a numeric variable -#' @rdname cutsplits +#' #' @inheritParams lyt_args #' @inheritParams constr_args +#' #' @exportClass VarStaticCutSplit +#' @rdname cutsplits setClass("VarStaticCutSplit", contains = "Split", representation( @@ -461,12 +453,14 @@ setClass("VarStaticCutSplit", } #' Create static cut or static cumulative cut split +#' #' @inheritParams lyt_args #' @inheritParams constr_args +#' +#' @return A `VarStaticCutSplit`, `CumulativeCutSplit` object for `make_static_cut_split`, or a `VarDynCutSplit` +#' object for [VarDynCutSplit()]. +#' #' @rdname cutsplits -#' @return a \code{VarStaticCutSplit}, \code{CumulativeCutSplit} object for -#' \code{make_static_cut_split}, or a \code{VarDynCutSplit} object for -#' \code{VarDynCutSplit()} make_static_cut_split <- function(var, split_label, cuts, @@ -527,23 +521,19 @@ make_static_cut_split <- function(var, ) } - - -#' @rdname cutsplits #' @exportClass CumulativeCutSplit - +#' @rdname cutsplits setClass("CumulativeCutSplit", contains = "VarStaticCutSplit") ## make_static_cut_split with cumulative=TRUE is the constructor ## for CumulativeCutSplit - ## do we want this to be a CustomizableSplit instead of ## taking cut_fun? ## cut_funct must take avector and no other arguments ## and return a named vector of cut points -#' @rdname cutsplits #' @exportClass VarDynCutSplit +#' @rdname cutsplits setClass("VarDynCutSplit", contains = "Split", representation( @@ -552,8 +542,9 @@ setClass("VarDynCutSplit", cumulative_cuts = "logical" ) ) -#' @rdname cutsplits + #' @export +#' @rdname cutsplits VarDynCutSplit <- function(var, split_label, cutfun, @@ -601,8 +592,6 @@ VarDynCutSplit <- function(var, ) } - - ## NB analyze splits can't have content-related things setClass("VAnalyzeSplit", contains = "Split", @@ -627,12 +616,13 @@ setClass("AnalyzeColVarSplit", #' #' @inheritParams lyt_args #' @inheritParams constr_args -#' @param defrowlab character. Default row labels if they are not specified by -#' the return value of \code{afun} -#' @rdname avarspl -#' @return An \code{AnalyzeVarSplit} object. +#' @param defrowlab (`character`)\cr default row labels, if not specified by the return value of `afun`. +#' +#' @return An `AnalyzeVarSplit` object. +#' #' @author Gabriel Becker #' @export +#' @rdname avarspl AnalyzeVarSplit <- function(var, split_label = var, afun, @@ -682,9 +672,10 @@ AnalyzeVarSplit <- function(var, #' #' @inheritParams lyt_args #' @inheritParams constr_args -#' @rdname avarspl +#' #' @author Gabriel Becker #' @export +#' @rdname avarspl AnalyzeColVarSplit <- function(afun, defrowlab = "", cfun = NULL, @@ -726,7 +717,6 @@ setClass("CompoundSplit", validity = function(object) are(object@payload, "Split") ) - setClass("AnalyzeMultiVars", contains = "CompoundSplit") .repoutlst <- function(x, nv) { @@ -739,7 +729,6 @@ setClass("AnalyzeMultiVars", contains = "CompoundSplit") rep(x, length.out = nv) } - .uncompound <- function(csplit) { if (is(csplit, "list")) { return(unlist(lapply(csplit, .uncompound))) @@ -773,10 +762,12 @@ make_ma_name <- function(spl, pld = spl_payload(spl)) { ) } -#' @rdname avarspl -#' @param .payload Used internally, not intended to be set by end users. -#' @return An \code{AnalyzeMultiVars} split object. +#' @param .payload (`list`)\cr used internally, not intended to be set by end users. +#' +#' @return An `AnalyzeMultiVars` split object. +#' #' @export +#' @rdname avarspl AnalyzeMultiVars <- function(var, split_label = "", afun, @@ -790,10 +781,7 @@ AnalyzeMultiVars <- function(var, split_name = NULL, extra_args = list(), indent_mod = 0L, - child_labels = c( - "default", "topleft", "visible", - "hidden" - ), + child_labels = c("default", "topleft", "visible", "hidden"), child_names = var, cvar = "", section_div = NA_character_) { @@ -888,13 +876,14 @@ AnalyzeMultiVars <- function(var, } ret } + setClass("VarLevWBaselineSplit", contains = "VarLevelSplit", representation( var = "character", ref_group_value = "character" ) -) # , +) #' @rdname VarLevelSplit #' @export @@ -943,7 +932,6 @@ VarLevWBaselineSplit <- function(var, ) } - .chkname <- function(nm) { if (is.null(nm)) { nm <- "" @@ -957,16 +945,11 @@ VarLevWBaselineSplit <- function(var, nm } - - - -### ### Tree Position Representation ### ### Class(es) that represent position with in a ### tree as parallel vectors of Split objects and ### values chosen at that split, plus labeling info - TreePos <- function(spls = list(), svals = list(), svlabels = character(), @@ -990,10 +973,8 @@ TreePos <- function(spls = list(), ) } -## ## Tree position convenience functions ## - make_child_pos <- function(parpos, newspl, newval, @@ -1017,13 +998,10 @@ make_child_pos <- function(parpos, newpos } - -# Virtual Classes for Tree Nodes and Layouts ================================= -### -### Virtual class hiearchy for the various types of -### trees in use in the S4 implementation of the TableTree -### machinery -### +## Virtual Classes for Tree Nodes and Layouts ================================= +## +## Virtual class hiearchy for the various types of trees in use in the S4 +## implementation of the TableTree machinery ## core basics setClass("VNodeInfo", @@ -1034,15 +1012,18 @@ setClass("VNodeInfo", ## label = "character" ) ) + setClass("VTree", contains = c("VIRTUAL", "VNodeInfo"), representation(children = "list") ) + setClass("VLeaf", contains = c("VIRTUAL", "VNodeInfo")) +## Layout trees ================================= -## Layout trees # setClass("VLayoutNode", contains= c("VIRTUAL", "VNodeInfo")) + setClass("VLayoutLeaf", contains = c("VIRTUAL", "VLeaf"), representation( @@ -1050,6 +1031,7 @@ setClass("VLayoutLeaf", label = "character" ) ) + setClass("VLayoutTree", contains = c("VIRTUAL", "VTree"), representation( @@ -1058,14 +1040,10 @@ setClass("VLayoutTree", label = "character" ) ) -setClassUnion("VLayoutNode", c("VLayoutLeaf", "VLayoutTree")) - +setClassUnion("VLayoutNode", c("VLayoutLeaf", "VLayoutTree")) - -## -## LayoutAxisTree classes -## +## LayoutAxisTree classes ================================= setOldClass("function") setOldClass("NULL") @@ -1087,7 +1065,6 @@ setClass("LayoutAxisLeaf", ) ) - setClass("LayoutColTree", contains = "LayoutAxisTree", representation( @@ -1148,8 +1125,6 @@ LayoutColLeaf <- function(lev = 0L, ) } - - ## Instantiated column info class ============================================== ## ## This is so we don't need multiple arguments @@ -1157,8 +1132,10 @@ LayoutColLeaf <- function(lev = 0L, ## various aspects of the column layout ## once its applied to the data. -#' `InstantiatedColumnInfo` +#' Instantiated column info +#' #' @inheritParams gen_args +#' #' @exportClass InstantiatedColumnInfo #' @rdname cinfo setClass( @@ -1176,20 +1153,21 @@ setClass( ) ) -#' @rdname cinfo -#' @export -#' @param treelyt `LayoutColTree`. -#' @param csubs list. List of subsetting expressions -#' @param extras list. Extra arguments associated with the columns -#' @param cnts integer. Counts. -#' @param total_cnt integer(1). Total observations represented across all -#' columns. -#' @param dispcounts logical(1). Should the counts be displayed as header info when -#' the associated table is printed. -#' @param countformat character(1). Format for the counts if they are displayed -#' @param count_na_str character. NA string to be used when formatting counts. Defaults +#' @param treelyt (`LayoutColTree`)\cr a `LayoutColTree` object. +#' @param csubs (`list`)\cr a list of subsetting expressions. +#' @param extras (`list`)\cr extra arguments associated with the columns. +#' @param cnts (`integer`)\cr counts. +#' @param total_cnt (`integer(1)`)\cr total observations represented across all columns. +#' @param dispcounts (`flag`)\cr whether the counts should be displayed as header info when the associated +#' table is printed. +#' @param countformat (`string`)\cr format for the counts if they are displayed. +#' @param count_na_str (`character`)\cr string to use in place of missing values when formatting counts. Defaults #' to `""`. -#' @return an \code{InstantiateadColumnInfo} object. +#' +#' @return An `InstantiateadColumnInfo` object. +#' +#' @export +#' @rdname cinfo InstantiatedColumnInfo <- function(treelyt = LayoutColTree(), csubs = list(expression(TRUE)), extras = list(list()), @@ -1205,8 +1183,6 @@ InstantiatedColumnInfo <- function(treelyt = LayoutColTree(), cnts <- rep(cnts, length.out = nl) csubs <- rep(csubs, length.out = nl) - - nleaves <- length(leaves) snas <- sum(is.na(cnts)) if (length(csubs) != nleaves || length(extras) != nleaves || length(cnts) != nleaves) { @@ -1237,7 +1213,6 @@ InstantiatedColumnInfo <- function(treelyt = LayoutColTree(), ) } - ## TableTrees and row classes ================================================== ## XXX Rowspans as implemented dont really work ## they're aren't attached to the right data structures @@ -1268,18 +1243,19 @@ setClass("TableRow", ) ) - - - -### TableTree Core non-virtual Classes +## TableTree Core Non-Virtual Classes ============== +## #' Row classes and constructors -#' @rdname rowclasses +#' #' @inheritParams constr_args #' @inheritParams lyt_args -#' @param vis logical. Should the row be visible (\code{LabelRow} only). -#' @author Gabriel Becker +#' @param vis (`flag`)\cr whether the row should be visible (`LabelRow` only). +#' #' @return A formal object representing a table row of the constructed type. +#' +#' @author Gabriel Becker #' @export +#' @rdname rowclasses LabelRow <- function(lev = 1L, label = "", name = label, @@ -1305,7 +1281,8 @@ LabelRow <- function(lev = 1L, ) } -#' Row constructors and Classes +#' Row constructors and classes +#' #' @rdname rowclasses #' @exportClass DataRow setClass("DataRow", @@ -1337,12 +1314,10 @@ setClass("LabelRow", representation(visible = "logical") ) - - -#' @rdname rowclasses -#' @param klass Internal detail. +#' @param klass (`character`)\cr internal detail. #' #' @export +#' @rdname rowclasses .tablerow <- function(vals = list(), name = "", lev = 1L, @@ -1390,12 +1365,14 @@ setClass("LabelRow", rw } -#' @rdname rowclasses -#' @param \dots passed to shared constructor (\code{.tablerow}). +#' @param ... additional parameters passed to shared constructor (`.tablerow`). +#' #' @export -DataRow <- function(...) .tablerow(..., klass = "DataRow") #' @rdname rowclasses +DataRow <- function(...) .tablerow(..., klass = "DataRow") + #' @export +#' @rdname rowclasses ContentRow <- function(...) .tablerow(..., klass = "ContentRow") setClass("VTitleFooter", @@ -1408,7 +1385,6 @@ setClass("VTitleFooter", ) ) - setClass("VTableTree", contains = c("VIRTUAL", "VTableNodeInfo", "VTree", "VTitleFooter"), representation( @@ -1437,9 +1413,11 @@ etable_validity <- function(object) { ## nocov end #' `TableTree` classes -#' @exportClass ElementaryTable -#' @author Gabriel Becker +#' #' @return A formal object representing a populated table. +#' +#' @author Gabriel Becker +#' @exportClass ElementaryTable #' @rdname tabclasses setClass("ElementaryTable", contains = "VTableTree", @@ -1491,14 +1469,16 @@ setClass("ElementaryTable", lst } -#' Table Constructors and Classes +#' Table constructors and classes +#' #' @inheritParams constr_args #' @inheritParams gen_args #' @inheritParams lyt_args -#' @param rspans data.frame. Currently stored but otherwise ignored. -#' @rdname tabclasses +#' @param rspans (`data.frame`)\cr currently stored but otherwise ignored. +#' #' @author Gabriel Becker #' @export +#' @rdname tabclasses ElementaryTable <- function(kids = list(), name = "", lev = 1L, @@ -1583,10 +1563,11 @@ ttable_validity <- function(object) { EmptyColInfo } } + ## under this model, non-leaf nodes can have a content table where rollup ## analyses live -#' @rdname tabclasses #' @exportClass TableTree +#' @rdname tabclasses setClass("TableTree", contains = c("VTableTree"), representation( @@ -1596,8 +1577,8 @@ setClass("TableTree", validity = ttable_validity ) -#' @rdname tabclasses #' @export +#' @rdname tabclasses TableTree <- function(kids = list(), name = if (!is.na(var)) var else "", cont = EmptyElTable, @@ -1692,16 +1673,12 @@ TableTree <- function(kids = list(), } } - -### ### Pre-Data Layout Declaration Classes ### ### Notably these are NOT represented as trees ### because without data we cannot know what the ### children should be. -### -## ## Vector (ordered list) of splits. ## ## This is a vector (ordered list) of splits to be @@ -1709,9 +1686,7 @@ TableTree <- function(kids = list(), ## ## For convenience, if this is length 1, it can contain ## a pre-existing TableTree/ElementaryTable. -## This is used for add_existing_table in -## colby_constructors.R -## +## This is used for add_existing_table in colby_constructors.R setClass("SplitVector", contains = "list", @@ -1746,8 +1721,6 @@ avar_noneorlast <- function(vec) { (length(isavar) == 0) || (length(isavar) == 1 && isavar == length(vec)) } - - setClass("PreDataAxisLayout", contains = "list", representation(root_split = "ANY"), @@ -1763,8 +1736,6 @@ setClass("PreDataAxisLayout", } ) - - setClass("PreDataColLayout", contains = "PreDataAxisLayout", representation( @@ -1789,7 +1760,6 @@ PreDataColLayout <- function(x = SplitVector(), ret } - PreDataRowLayout <- function(x = SplitVector(), root = RootSplit(), ..., @@ -1797,9 +1767,6 @@ PreDataRowLayout <- function(x = SplitVector(), new("PreDataRowLayout", lst, root_split = root) } - - - setClass("PreDataTableLayouts", contains = "VTitleFooter", representation( @@ -1836,8 +1803,6 @@ PreDataTableLayouts <- function(rlayout = PreDataRowLayout(), ) } - - ## setClass("CellValue", contains = "ValueWrapper", ## representation(format = "FormatSpec", ## colspan = "integerOrNULL", @@ -1848,9 +1813,11 @@ setOldClass("CellValue") #' Length of a Cell value #' +#' @param x (`CellValue`)\cr a `CellValue` object. +#' +#' @return Always returns `1L`. +#' #' @exportMethod length -#' @return Always returns \code{1L} -#' @param x x. setMethod( "length", "CellValue", function(x) 1L @@ -1862,7 +1829,6 @@ setClass("RefFootnote", representation( symbol = "character" )) - RefFootnote <- function(note, index = NA_integer_, symbol = NA_character_) { if (is(note, "RefFootnote")) { return(note) @@ -1885,16 +1851,15 @@ RefFootnote <- function(note, index = NA_integer_, symbol = NA_character_) { new("RefFootnote", value = note, index = index, symbol = symbol) } -#' Cell Value constructor +#' Constructor for Cell Value #' #' @inheritParams lyt_args #' @inheritParams rcell -#' @param val ANY. value in the cell exactly as it should be passed to a -#' formatter or returned when extracted -#' @return An object representing the value within a single cell within a -#' populated table. The underlying structure of this object is an -#' implementation detail and should not be relied upon beyond calling -#' accessors for the class. +#' @param val (`ANY`)\cr value in the cell exactly as it should be passed to a formatter or returned when extracted. +#' +#' @return An object representing the value within a single cell within a populated table. The underlying structure +#' of this object is an implementation detail and should not be relied upon beyond calling accessors for the class. +#' #' @export ## Class definition @@ -1934,8 +1899,8 @@ CellValue <- function(val, format = NULL, colspan = 1L, label = NULL, ret } - #' @method print CellValue +#' #' @export print.CellValue <- function(x, ...) { cat(paste("rcell:", format_rcell(x), "\n")) @@ -1948,7 +1913,6 @@ print.CellValue <- function(x, ...) { # row_labels = "characterOrNULL", # row_formats = "ANY", # indent_mods = "integerOrNULL")) -# setOldClass("RowsVerticalSection") RowsVerticalSection <- function(values, @@ -1988,8 +1952,8 @@ RowsVerticalSection <- function(values, ) } - #' @method print RowsVerticalSection +#' #' @export print.RowsVerticalSection <- function(x, ...) { cat("RowsVerticalSection (in_rows) object print method:\n-------------------", @@ -2007,8 +1971,7 @@ print.RowsVerticalSection <- function(x, ...) { invisible(x) } - -## ## Empty default objects to avoid repeated calls +#### Empty default objects to avoid repeated calls ## EmptyColInfo <- InstantiatedColumnInfo() ## EmptyElTable <- ElementaryTable() ## EmptyRootSplit <- RootSplit() diff --git a/R/Viewer.R b/R/Viewer.R index 3e86d306b..fb0b93d6f 100644 --- a/R/Viewer.R +++ b/R/Viewer.R @@ -1,15 +1,15 @@ -#' @importFrom utils browseURL +#' @importFrom utils browseURL NULL -#' Display an [`rtable`] object in the Viewer pane in RStudio or in a browser +#' Display an `rtable` object in the Viewer pane in RStudio or in a browser #' -#' The table will be displayed using the bootstrap styling for tables. +#' The table will be displayed using bootstrap styling. #' -#' @param x object of class `rtable` or `shiny.tag` (defined in `htmltools` package) -#' @param y optional second argument of same type as `x` -#' @param ... arguments passed to [`as_html`] +#' @param x (`rtable` or `shiny.tag`)\cr an object of class `rtable` or `shiny.tag` (defined in `htmltools` package). +#' @param y (`rtable` or `shiny.tag`)\cr optional second argument of same type as `x`. +#' @param ... arguments passed to [as_html()]. #' -#' @return not meaningful. Called for the side effect of opening a browser or viewer pane. +#' @return Not meaningful. Called for the side effect of opening a browser or viewer pane. #' #' @examples #' if (interactive()) { diff --git a/R/argument_conventions.R b/R/argument_conventions.R index 6c14f1f6f..f004a0fa1 100644 --- a/R/argument_conventions.R +++ b/R/argument_conventions.R @@ -1,73 +1,51 @@ # nocov start -## package imports -#' @importFrom utils head head.matrix tail tail.matrix -#' @importFrom stats setNames na.omit prop.test binom.test relevel quantile -#' @importFrom htmltools tags tagList -#' @importFrom magrittr %>% -#' @import methods -NULL - -#' General Argument Conventions -#' @name gen_args -#' @inheritParams formatters::format_value +#' General argument conventions +#' +#' @param ... additional parameters passed to methods or tabulation functions. +#' @param alt_counts_df (`data.frame` or `tibble`)\cr alternative full dataset the rtables framework will use +#' *only* when calculating column counts. +#' @param colwidths (`numeric`)\cr a vector of column widths for use in vertical pagination. +#' @param cvar (`string`)\cr the variable, if any, that the content function should accept. Defaults to `NA`. +#' @param df (`data.frame` or `tibble`)\cr dataset. +#' @param hsep (`string`)\cr set of characters to be repeated as the separator between the header and body of +#' the table when rendered as text. Defaults to a connected horizontal line (unicode 2014) in locals that use a UTF +#' charset, and to `-` elsewhere (with a once per session warning). See [formatters::set_default_hsep()] for further +#' information. +#' @param indent_size (`numeric(1)`)\cr number of spaces to use per indent level. Defaults to 2. +#' @param inset (`numeric(1)`)\cr number of spaces to inset the table header, table body, referential footnotes, and +#' main_footer, as compared to alignment of title, subtitle, and provenance footer. Defaults to 0 (no inset). +#' @param label (`string`)\cr a label (not to be confused with the name) for the object/structure. +#' @param label_pos (`string`)\cr location where the variable label should be displayed. Accepts `"hidden"` +#' (default for non-analyze row splits), `"visible"`, `"topleft"`, and `"default"` (for analyze splits only). For +#' `analyze` calls, `"default"` indicates that the variable should be visible if and only if multiple variables are +#' analyzed at the same level of nesting. +#' @param na_str (`string`)\cr string that should be displayed when the value of `x` is missing. Defaults to `"NA"`. +#' @param obj (`ANY`)\cr the object for the accessor to access or modify. +#' @param object (`ANY`)\cr the object to modify in place. +#' @param page_prefix (`string`)\cr prefix to be appended with the split value when forcing pagination between +#' the children of a split/table. +#' @param path (`character`)\cr a vector path for a position within the structure of a `TableTree`. Each element +#' represents a subsequent choice amongst the children of the previous choice. +#' @param pos (`numeric`)\cr which top-level set of nested splits should the new layout feature be added to. Defaults +#' to the current split. +#' @param section_div (`string`)\cr string which should be repeated as a section divider after each group defined +#' by this split instruction, or `NA_character_` (the default) for no section divider. +#' @param spl (`Split`)\cr a `Split` object defining a partitioning or analysis/tabulation of the data. +#' @param table_inset (`numeric(1)`)\cr number of spaces to inset the table header, table body, referential footnotes, +#' and main footer, as compared to alignment of title, subtitles, and provenance footer. Defaults to 0 (no inset). +#' @param topleft (`character`)\cr override values for the "top left" material to be displayed during printing. +#' @param tr (`TableRow` or related class)\cr a `TableRow` object representing a single row within a populated table. +#' @param tt (`TableTree` or related class)\cr a `TableTree` object representing a populated table. +#' @param value (`ANY`)\cr the new value. +#' @param verbose (`flag`)\cr whether additional information should be displayed to the user. Defaults to `FALSE`. +#' @param x (`ANY`)\cr an object. +#' +#' @return No return value. +#' #' @family conventions -#' @param df dataset (`data.frame` or `tibble`) -#' @param alt_counts_df dataset (`data.frame` or `tibble`). Alternative full data -#' the rtables framework will use (\emph{only}) when calculating column -#' counts. -#' @param spl A Split object defining a partitioning or analysis/tabulation of -#' the data. -#' @param pos numeric. Which top-level set of nested splits should the new -#' layout feature be added to. Defaults to the current -#' @param tt `TableTree` (or related class). A `TableTree` object representing a -#' populated table. -#' @param tr `TableRow` (or related class). A `TableRow` object representing a -#' single row within a populated table. -#' @param verbose logical. Should additional information be displayed to the -#' user. Defaults to FALSE. -#' @param colwidths numeric vector. Column widths for use with vertical pagination. -#' @param obj ANY. The object for the accessor to access or modify -#' @param x An object -#' @param \dots Passed on to methods or tabulation functions. -#' @param value The new value -#' @param object The object to modify in-place -#' @param verbose logical(1). Should extra debugging messages be shown. Defaults -#' to \code{FALSE}. -#' @param path character. A vector path for a position within the structure of a -#' `tabletree`. Each element represents a subsequent choice amongst the children -#' of the previous choice. -#' @param label character(1). A label (not to be confused with the name) for the -#' object/structure. -#' @param label_pos character(1). Location the variable label should be -#' displayed, Accepts `"hidden"` (default for non-analyze row splits), `"visible"`, -#' `"topleft"`, and - for analyze splits only - `"default"`. For analyze calls, -#' `"default"` indicates that the variable should be visible if and only if -#' multiple variables are analyzed at the same level of nesting. -#' @param cvar character(1). The variable, if any, which the content function -#' should accept. Defaults to NA. -#' @param topleft character. Override values for the "top left" material to be -#' displayed during printing. -#' @param page_prefix character(1). Prefix, to be appended with the split value, -#' when forcing pagination between the children of this split/table -#' @param hsep character(1). Set of character(s) to be repeated as the separator -#' between the header and body of the table when rendered as text. Defaults to -#' a connected horizontal line (unicode 2014) in locals that use a UTF -#' charset, and to `-` elsewhere (with a once per session warning). See -#' [formatters::set_default_hsep()] for further information. -#' @param indent_size numeric(1). Number of spaces to use per indent level. -#' Defaults to 2 -#' @param section_div character(1). String which should be repeated as a section -#' divider after each group defined by this split instruction, or -#' `NA_character_` (the default) for no section divider. -#' @param inset numeric(1). Number of spaces to inset the table header, table -#' body, referential footnotes, and main_footer, as compared to alignment -#' of title, subtitle, and provenance footer. Defaults to 0 (no inset). -#' @param table_inset numeric(1). Number of spaces to inset the table header, table -#' body, referential footnotes, and main_footer, as compared to alignment -#' of title, subtitle, and provenance footer. Defaults to 0 (no inset). -#' @return NULL (this is an argument template dummy function) -#' @rdname gen_args +#' @name gen_args +#' @keywords internal gen_args <- function(df, alt_counts_df, spl, pos, tt, tr, verbose, colwidths, obj, x, value, object, path, label, label_pos, # visible_label, cvar, topleft, page_prefix, hsep, indent_size, section_div, na_str, inset, @@ -76,100 +54,80 @@ gen_args <- function(df, alt_counts_df, spl, pos, tt, tr, verbose, colwidths, ob NULL } -#' Layouting Function Arg Conventions -#' @name lyt_args -#' @rdname lyt_args +#' Layouting function argument conventions +#' #' @inheritParams gen_args -#' @param lyt layout object pre-data used for tabulation -#' @param var string, variable name -#' @param vars character vector. Multiple variable names. -#' @param var_labels character. Variable labels for 1 or more variables -#' @param labels_var string, name of variable containing labels to be displayed -#' for the values of \code{var} -#' @param varlabels character vector. Labels for \code{vars} -#' @param varnames character vector. Names for \code{vars} which will appear in -#' pathing. When \code{vars} are all unique this will be the variable names. -#' If not, these will be variable names with suffixes as necessary to enforce -#' uniqueness. -#' @param split_format `FormatSpec`. Default format associated with the split -#' being created. -#' @param split_na_str character. NA string vector for use with \code{split_format}. -#' @param split_label string. Label string to be associated with the table -#' generated by the split. Not to be confused with labels assigned to each -#' child (which are based on the data and type of split during tabulation). -#' @param nested boolean. Should this layout instruction be applied within the -#' existing layout structure \emph{if possible} (`TRUE`, the default) or as a -#' new top-level element (`FALSE). Ignored if it would nest a split underneath -#' analyses, which is not allowed. -#' @param format `FormatSpec`. Format associated with this split. Formats can be -#' declared via strings (\code{"xx.x"}) or function. In cases such as -#' \code{analyze} calls, they can character vectors or lists of functions. -#' @param align character(1) or `NULL`. Alignment the value should be rendered with. -#' It defaults to `"center"` if `NULL` is used. See [formatters::list_valid_aligns()] -#' for currently supported alignments. -#' @param cfun list/function/NULL. tabulation function(s) for creating content -#' rows. Must accept \code{x} or \code{df} as first parameter. Must accept -#' \code{labelstr} as the second argument. Can optionally accept all optional -#' arguments accepted by analysis functions. See \code{\link{analyze}}. -#' @param cformat format spec. Format for content rows -#' @param cna_str character. NA string for use with \code{cformat} for content -#' table. -#' @param split_fun function/NULL. custom splitting function See -#' \code{\link{custom_split_funs}} -#' @param split_name string. Name associated with this split (for pathing, etc) -#' @param afun function. Analysis function, must take \code{x} or \code{df} as -#' its first parameter. Can optionally take other parameters which will be -#' populated by the tabulation framework. See Details in -#' \code{\link{analyze}}. -#' @param inclNAs boolean. Should observations with NA in the \code{var} -#' variable(s) be included when performing this analysis. Defaults to -#' \code{FALSE} -#' @param valorder character vector. Order that the split children should appear -#' in resulting table. -#' @param ref_group character. Value of \code{var} to be taken as the -#' ref_group/control to be compared against. -#' @param compfun function/string. The comparison function which accepts the -#' analysis function outputs for two different partitions and returns a single -#' value. Defaults to subtraction. If a string, taken as the name of a +#' @param afun (`function`)\cr analysis function. Must accept `x` or `df` as its first parameter. Can optionally take +#' other parameters which will be populated by the tabulation framework. See Details in [analyze()]. +#' @param align (`string` or `NULL`)\cr alignment the value should be rendered with. Defaults to `"center"` if +#' `NULL` is used. See [formatters::list_valid_aligns()] for all currently supported alignments. +#' @param cformat (`string`, `function`, or `list`)\cr format for content rows. +#' @param cfun (`list`, `function`, or `NULL`)\cr tabulation function(s) for creating content rows. Must accept `x` +#' or `df` as first parameter. Must accept `labelstr` as the second argument. Can optionally accept all optional +#' arguments accepted by analysis functions. See [analyze()]. +#' @param child_labels (`string`)\cr the display behavior for the labels (i.e. label rows) of the children of this +#' split. Accepts `"default"`, `"visible"`, and `"hidden"`. Defaults to `"default"` which flags the label row as +#' visible only if the child has 0 content rows. +#' @param cna_str (`character`)\cr NA string for use with `cformat` for content table. +#' @param compfun (`function` or `string`)\cr the comparison function which accepts the analysis function outputs for +#' two different partitions and returns a single value. Defaults to subtraction. If a string, taken as the name of a #' function. -#' @param label_fstr string. An `sprintf` style format string containing. For -#' non-comparison splits, it can contain up to one \code{"\%s"} which takes -#' the current split value and generates the row/column label. -#' Comparison-based splits it can contain up to two \code{"\%s"}. -#' @param child_labels string. One of \code{"default"}, \code{"visible"}, -#' \code{"hidden"}. What should the display behavior be for the labels (i.e. -#' label rows) of the children of this split. Defaults to \code{"default"} -#' which flags the label row as visible only if the child has 0 content rows. -#' @param extra_args list. Extra arguments to be passed to the tabulation -#' function. Element position in the list corresponds to the children of this -#' split. Named elements in the child-specific lists are ignored if they do +#' @param cumulative (`flag`)\cr whether the cuts should be treated as cumulative. Defaults to `FALSE`. +#' @param cutfun (`function`)\cr function which accepts the *full vector* of `var` values and returns cut points to be +#' used (via `cut`) when splitting data during tabulation. +#' @param cutlabels (`character` or `NULL`)\cr labels for the cuts. +#' @param cutlabelfun (`function`)\cr function which returns either labels for the cuts or `NULL` when passed the +#' return value of `cutfun`. +#' @param cuts (`numeric`)\cr cuts to use. +#' @param extra_args (`list`)\cr extra arguments to be passed to the tabulation function. Element position in the list +#' corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do #' not match a formal argument of the tabulation function. -#' @param name character(1). Name of the split/table/row being created. Defaults -#' to same as the corresponding label, but is not required to be. -#' @param cuts numeric. Cuts to use -#' @param cutlabels character (or NULL). Labels for the cuts -#' @param cutlabelfun function. Function which returns either labels for the -#' cuts or NULL when passed the return value of \code{cutfun} -#' @param cumulative logical. Should the cuts be treated as cumulative. Defaults -#' to \code{FALSE} -#' @param cutfun function. Function which accepts the \emph{full vector} of -#' \code{var} values and returns cut points to be used (via \code{cut}) when -#' splitting data during tabulation -#' @param indent_mod numeric. Modifier for the default indent position for the -#' structure created by this function(subtable, content table, or row) -#' \emph{and all of that structure's children}. Defaults to 0, which +#' @param format (`string`, `function`, or `list`)\cr format associated with this split. Formats can be declared via +#' strings (`"xx.x"`) or function. In cases such as `analyze` calls, they can be character vectors or lists of +#' functions. See [formatters::list_valid_format_labels()] for a list of all available format strings. +#' @param format_na_str (`string`)\cr string which should be displayed when formatted if this cell's value(s) +#' are all `NA`. +#' @param indent_mod (`numeric`)\cr modifier for the default indent position for the structure created by this +#' function (subtable, content table, or row) *and all of that structure's children*. Defaults to 0, which #' corresponds to the unmodified default behavior. -#' @param show_labels character(1). Should the variable labels for corresponding -#' to the variable(s) in \code{vars} be visible in the resulting table. -#' @param table_names character. Names for the tables representing each atomic -#' analysis. Defaults to \code{var}. -#' @param page_by logical(1). Should pagination be forced between different -#' children resulting form this split. An error will rise if the selected split -#' does not contain at least one value that is not `NA`. -#' @param format_na_str character(1). String which should be displayed when -#' formatted if this cell's value(s) are all NA. +#' @param inclNAs (`logical`)\cr whether NA observations in the `var` variable(s) should be included when performing +#' the analysis. Defaults to `FALSE`. +#' @param label_fstr (`string`)\cr a `sprintf` style format string. For non-comparison splits, it can contain up to +#' one `"\%s"` which takes the current split value and generates the row/column label. For comparison-based splits +#' it can contain up to two `"\%s"`. +#' @param labels_var (`string`)\cr name of variable containing labels to be displayed for the values of `var`. +#' @param lyt (`PreDataTableLayouts`)\cr layout object pre-data used for tabulation. +#' @param name (`string`)\cr name of the split/table/row being created. Defaults to the value of the +#' corresponding label, but is not required to be. +#' @param nested (`logical`)\cr whether this layout instruction should be applied within the existing layout structure +#' *if possible* (`TRUE`, the default) or as a new top-level element (`FALSE`). Ignored if it would nest a split +#' underneath analyses, which is not allowed. +#' @param page_by (`flag`)\cr whether pagination should be forced between different children resulting from this +#' split. An error will occur if the selected split does not contain at least one value that is not `NA`. +#' @param ref_group (`character`)\cr value of `var` to be taken as the `ref_group`/control to be compared against. +#' @param show_labels (`string`)\cr whether the variable labels corresponding to the variable(s) in `vars` +#' should be visible in the resulting table. +#' @param split_format (`string`, `function`, or `list`)\cr default format associated with the split being created. +#' @param split_fun (`function` or `NULL`)\cr custom splitting function. See [custom_split_funs]. +#' @param split_label (`string`)\cr label to be associated with the table generated by the split. Not to be confused +#' with labels assigned to each child (which are based on the data and type of split during tabulation). +#' @param split_name (`string`)\cr name associated with the split (for pathing, etc.). +#' @param split_na_str (`character`)\cr NA string vector for use with `split_format`. +#' @param table_names (`character`)\cr names for the tables representing each atomic analysis. Defaults to `var`. +#' @param valorder (`character`)\cr the order that the split children should appear in resulting table. +#' @param var (`string`)\cr variable name. +#' @param varlabels (`character`)\cr vector of labels for `vars`. +#' @param varnames (`character`)\cr vector of names for `vars` which will appear in pathing. When `vars` are all +#' unique this will be the variable names. If not, these will be variable names with suffixes as necessary to enforce +#' uniqueness. +#' @param vars (`character`)\cr vector of variable names. +#' @param var_labels (`character`)\cr vector of labels for one or more variables. +#' #' @inherit gen_args return +#' #' @family conventions +#' @name lyt_args +#' @keywords internal lyt_args <- function(lyt, var, vars, label, labels_var, varlabels, varnames, split_format, split_na_str, nested, format, cfun, cformat, cna_str, split_fun, split_name, split_label, afun, inclNAs, valorder, @@ -182,56 +140,48 @@ lyt_args <- function(lyt, var, vars, label, labels_var, varlabels, varnames, spl NULL } - -#' Constructor Arg Conventions -#' @name constr_args -#' @family conventions -#' @inherit gen_args return +#' Constructor argument conventions #' #' @inheritParams gen_args #' @inheritParams lyt_args -#' @param kids list. List of direct children. -#' @param cont `ElementaryTable`. Content table. -#' @param lev integer. Nesting level (roughly, indentation level in practical -#' terms). -#' @param iscontent logical. Is the `TableTree`/`ElementaryTable` being constructed -#' the content table for another `TableTree`. -#' @param cinfo `InstantiatedColumnInfo` (or NULL). Column structure for the -#' object being created. -#' @param labelrow `LabelRow`. The `LabelRow` object to assign to this Table. -#' Constructed from \code{label} by default if not specified. -#' @param vals list. cell values for the row -#' @param cspan integer. Column span. \code{1} indicates no spanning. -#' @param cindent_mod numeric(1). The indent modifier for the content tables -#' generated by this split. -#' @param cextra_args list. Extra arguments to be passed to the content function -#' when tabulating row group summaries. -#' @param child_names character. Names to be given to the sub splits contained -#' by a compound split (typically a `AnalyzeMultiVars` split object). -#' @param title character(1). Main title ([main_title()]) is a single string. -#' Ignored for subtables. -#' @param subtitles character. Subtitles ([subtitles()]) can be vector of strings, where -#' every element is printed in a separate line. Ignored for subtables. -#' @param main_footer character. Main global (non-referential) footer materials -#' ([main_footer()]). If it is a vector of strings, they will be printed on separate -#' lines. -#' @param prov_footer character. Provenance-related global footer materials -#' ([prov_footer()]). It can be also a vector of strings, printed on different lines. -#' Generally should not be modified by hand. -#' @param footnotes list or NULL. Referential footnotes to be applied at current -#' level. In post-processing, this can be achieved with [`fnotes_at_path<-`]. -#' @param trailing_section_div character(1). String which will be used as a section -#' divider after the printing of the last row contained in this (sub)-table, -#' unless that row is also the last table row to be printed overall, or -#' `NA_character_` for none (the default). When generated via layouting, this -#' would correspond to the `section_div` of the split under which this table -#' represents a single facet. -#' @param header_section_div character(1). String which will be used to divide the header -#' from the table. See [header_section_div()] for getter and setter of these. -#' Please consider changing last element of [section_div()] when concatenating -#' tables that need a divider between them. -#' @param page_title character. Page specific title(s). -#' @rdname constr_args +#' @param cextra_args (`list`)\cr extra arguments to be passed to the content function when tabulating row group +#' summaries. +#' @param child_names (`character`)\cr names to be given to the subsplits contained by a compound split (typically +#' an `AnalyzeMultiVars` split object). +#' @param cindent_mod (`numeric(1)`)\cr the indent modifier for the content tables generated by this split. +#' @param cinfo (`InstantiatedColumnInfo` or `NULL`)\cr column structure for the object being created. +#' @param cont (`ElementaryTable`)\cr content table. +#' @param cspan (`integer`)\cr column span. `1` indicates no spanning. +#' @param footnotes (`list` or `NULL`)\cr referential footnotes to be applied at current level. In post-processing, +#' this can be achieved with [`fnotes_at_path<-`]. +#' @param header_section_div (`string`)\cr string which will be used to divide the header from the table. See +#' [header_section_div()] for the associated getter and setter. Please consider changing last element of +#' [section_div()] when concatenating tables that require a divider between them. +#' @param iscontent (`flag`)\cr whether the `TableTree`/`ElementaryTable` is being constructed as the content +#' table for another `TableTree`. +#' @param kids (`list`)\cr list of direct children. +#' @param labelrow (`LabelRow`)\cr the `LabelRow` object to assign to the table. Constructed from `label` by default +#' if not specified. +#' @param lev (`integer(1)`)\cr nesting level (roughly, indentation level in practical terms). +#' @param main_footer (`character`)\cr a vector of strings to use as main global (non-referential) footer materials +#' ([main_footer()]), where every element is printed on a separate line. +#' @param page_title (`character`)\cr page-specific title(s). +#' @param prov_footer (`character`)\cr a vector of strings to use as provenance-related global footer materials +#' ([prov_footer()]), where every element is printed on a separate line. +#' @param subtitles (`character`)\cr a vector of strings to use as subtitles ([subtitles()]), where every element is +#' printed on a separate line. Ignored for subtables. +#' @param title (`string`)\cr single string to use as main title ([main_title()]). Ignored for subtables. +#' @param trailing_section_div (`string`)\cr string which will be used as a section divider after the printing +#' of the last row contained in this (sub)table, unless that row is also the last table row to be printed overall, +#' or `NA_character_` for none (the default). When generated via layouting, this would correspond to the +#' `section_div` of the split under which this table represents a single facet. +#' @param vals (`list`)\cr cell values for the row. +#' +#' @inherit gen_args return +#' +#' @family conventions +#' @name constr_args +#' @keywords internal constr_args <- function(kids, cont, lev, iscontent, cinfo, labelrow, vals, cspan, label_pos, cindent_mod, cvar, label, cextra_args, child_names, title, subtitles, main_footer, prov_footer, @@ -241,39 +191,36 @@ constr_args <- function(kids, cont, lev, iscontent, cinfo, labelrow, vals, NULL } -#' Compatibility Arg Conventions -#' @name compat_args -#' @family conventions -#' @inherit gen_args return +#' Compatibility argument conventions +#' #' @inheritParams gen_args -#' @param .lst list. An already-collected list of arguments to be used instead -#' of the elements of \code{\dots}. Arguments passed via \code{\dots} will be -#' ignored if this is specified. -#' @param row.name if \code{NULL} then an empty string is used as -#' \code{row.name} of the \code{\link{rrow}}. -#' @param format character(1) or function. The format label (string) or -#' formatter function to apply to the cell values passed via `...`. See -#' \code{\link[formatters]{list_valid_format_labels}} for currently supported -#' format labels. -#' @param indent deprecated. -#' @param inset integer(1). The table inset for the row or table being -#' constructed. See \code{\link[formatters]{table_inset}}. -#' @rdname compat_args +#' @param .lst (`list`)\cr an already-collected list of arguments to be used instead of the elements of `...`. +#' Arguments passed via `...` will be ignored if this is specified. +#' @param format (`string`, `function`, or `list`)\cr the format label (string) or formatter function to apply to the +#' cell values passed via `...`. See [formatters::list_valid_format_labels()] for currently supported format labels. +#' @param indent `r lifecycle::badge("deprecated")` +#' @param inset (`integer(1)`)\cr the table inset for the row or table being constructed. See +#' [formatters::table_inset()] for details. +#' @param row.name (`string` or `NULL`)\cr row name. If `NULL`, an empty string is used as `row.name` of the +#' [rrow()]. +#' +#' @inherit gen_args return +#' +#' @family conventions +#' @name compat_args compat_args <- function(.lst, row.name, format, indent, label, inset) NULL - - -#' Split Function Arg Conventions -#' @name sf_args -#' @family conventions -#' @inherit gen_args return +#' Split function argument conventions #' #' @inheritParams gen_args -#' @param trim logical(1). Should splits corresponding with 0 observations be -#' kept when tabulating. -#' @param first logical(1). Should the created split level be placed first in -#' the levels (\code{TRUE}) or last (\code{FALSE}, the default). +#' @param first (`flag`)\cr whether the created split level should be placed first in the levels (`TRUE`) or +#' last (`FALSE`, the default). +#' @param trim (`flag`)\cr whether splits corresponding with 0 observations should be kept when tabulating. +#' +#' @inherit gen_args return #' +#' @family conventions +#' @name sf_args sf_args <- function(trim, label, first) NULL # nocov end diff --git a/R/as_html.R b/R/as_html.R index bd25885cb..16ee1daab 100644 --- a/R/as_html.R +++ b/R/as_html.R @@ -14,28 +14,30 @@ insert_brs <- function(vec) { ret } - div_helper <- function(lst, class) { do.call(tags$div, c(list(class = paste(class, "rtables-container"), lst))) } -#' Convert an `rtable` object to a `shiny.tag` html object +#' Convert an `rtable` object to a `shiny.tag` HTML object +#' +#' The returned HTML object can be immediately used in `shiny` and `rmarkdown`. #' -#' The returned `html` object can be immediately used in `shiny` and `rmarkdown`. +#' @param x (`VTableTree`)\cr a `TableTree` object. +#' @param class_table (`character`)\cr class for `table` tag. +#' @param class_tr (`character`)\cr class for `tr` tag. +#' @param class_th (`character`)\cr class for `th` tag. +#' @param width (`character`)\cr a string to indicate the desired width of the table. Common input formats include a +#' percentage of the viewer window width (e.g. `"100%"`) or a distance value (e.g. `"300px"`). Defaults to `NULL`. +#' @param link_label (`character`)\cr link anchor label (not including `tab:` prefix) for the table. +#' @param bold (`character`)\cr elements in table output that should be bold. Options are `"main_title"`, +#' `"subtitles"`, `"header"`, `"row_names"`, `"label_rows"`, and `"content_rows"` (which includes any non-label +#' rows). Defaults to `"header"`. +#' @param header_sep_line (`flag`)\cr whether a black line should be printed to under the table header. Defaults +#' to `TRUE`. +#' @param no_spaces_between_cells (`flag`)\cr whether spaces between table cells should be collapsed. Defaults +#' to `FALSE`. #' -#' @param x `rtable` object -#' @param class_table class for `table` tag -#' @param class_tr class for `tr` tag -#' @param class_th class for `th` tag -#' @param width a string to indicate the desired width of the table. Common input formats include a -#' percentage of the viewer window width (e.g. `"100%"`) or a distance value (e.g. `"300px"`). -#' Defaults to `NULL`. -#' @param link_label link anchor label (not including `tab:` prefix) for the table. -#' @param bold elements in table output that should be bold. Options are `"main_title"`, `"subtitles"`, -#' `"header"`, `"row_names"`, `"label_rows"`, and `"content_rows"` (which includes any non-label rows). -#' Defaults to `"header"`. -#' @param header_sep_line whether a black line should be printed to under the table header. Defaults to `TRUE`. -#' @param no_spaces_between_cells whether spaces between table cells should be collapsed. Defaults to `FALSE`. +#' @importFrom htmltools tags #' #' @return A `shiny.tag` object representing `x` in HTML. #' @@ -58,7 +60,6 @@ div_helper <- function(lst, class) { #' Viewer(tbl) #' } #' -#' @importFrom htmltools tags #' @export as_html <- function(x, width = NULL, @@ -199,7 +200,6 @@ as_html <- function(x, ) ) - tabletag <- do.call( tags$table, c( diff --git a/R/colby_constructors.R b/R/colby_constructors.R index e4cceb951..d7105a93d 100644 --- a/R/colby_constructors.R +++ b/R/colby_constructors.R @@ -4,12 +4,15 @@ label_pos_values <- c("hidden", "visible", "topleft") #' @rdname int_methods NULL -#' combine `SplitVector` objects -#' @param x `SplitVecttor` -#' @param ... Splits or `SplitVector` objects -#' @exportMethod c +#' Combine `SplitVector` objects +#' +#' @param x (`SplitVector`)\cr a `SplitVector` object. +#' @param ... splits or `SplitVector` objects. +#' #' @return Various, but should be considered implementation details. +#' #' @rdname int_methods +#' @exportMethod c setMethod("c", "SplitVector", function(x, ...) { arglst <- list(...) stopifnot(all(sapply(arglst, is, "Split"))) @@ -28,9 +31,10 @@ setMethod("c", "SplitVector", function(x, ...) { ## The cascading (by class) in this case is as follows for the row case: ## PreDataTableLayouts -> PreDataRowLayout -> SplitVector -#' @param cmpnd_fun function. Intended for internal use. -#' @param pos numeric(1). Intended for internal use. -#' @param spl Split. The split. +#' @param cmpnd_fun (`function`)\cr intended for internal use. +#' @param pos (`numeric(1)`)\cr intended for internal use. +#' @param spl (`Split`)\cr the split. +#' #' @rdname int_methods setGeneric( "split_rows", @@ -47,6 +51,7 @@ setMethod("split_rows", "NULL", function(lyt, spl, pos, cmpnd_fun = AnalyzeMulti cl <- PreDataColLayout() PreDataTableLayouts(rlayout = rl, clayout = cl) }) + #' @rdname int_methods setMethod( "split_rows", "PreDataRowLayout", @@ -116,6 +121,7 @@ setMethod( lyt } ) + #' @rdname int_methods setMethod( "split_rows", "ANY", @@ -124,13 +130,18 @@ setMethod( } ) +## cmpnd_last_rowsplit ===== + #' @rdname int_methods -#' @param constructor function. +#' +#' @param constructor (`function`)\cr constructor function. setGeneric("cmpnd_last_rowsplit", function(lyt, spl, constructor) standardGeneric("cmpnd_last_rowsplit")) + #' @rdname int_methods setMethod("cmpnd_last_rowsplit", "NULL", function(lyt, spl, constructor) { stop("no existing splits to compound with. contact the maintainer") # nocov }) + #' @rdname int_methods setMethod( "cmpnd_last_rowsplit", "PreDataRowLayout", @@ -185,6 +196,7 @@ setMethod( } ) +## split_cols ==== #' @rdname int_methods setGeneric( @@ -204,6 +216,7 @@ setMethod("split_cols", "NULL", function(lyt, spl, pos) { rl <- PreDataRowLayout() PreDataTableLayouts(rlayout = rl, clayout = cl) }) + #' @rdname int_methods setMethod( "split_cols", "PreDataColLayout", @@ -219,6 +232,7 @@ setMethod( lyt } ) + #' @rdname int_methods setMethod( "split_cols", "SplitVector", @@ -227,6 +241,7 @@ setMethod( SplitVector(lst = tmp) } ) + #' @rdname int_methods setMethod( "split_cols", "PreDataTableLayouts", @@ -237,6 +252,7 @@ setMethod( lyt } ) + #' @rdname int_methods setMethod( "split_cols", "ANY", @@ -248,33 +264,23 @@ setMethod( } ) - -# constructors ---- - - +# Constructors ===== ## Pipe-able functions to add the various types of splits to the current layout ## for both row and column. These all act as wrappers to the split_cols and ## split_rows method stacks. - #' Declaring a column-split based on levels of a variable #' -#' Will generate children for each subset of a categorical variable -#' -#' -#' @inheritSection custom_split_funs Custom Splitting Function Details +#' Will generate children for each subset of a categorical variable. #' #' @inheritParams lyt_args +#' @param ref_group (`string` or `NULL`)\cr level of `var` that should be considered `ref_group`/reference. #' -#' @param ref_group character(1) or `NULL`. Level of `var` which should be -#' considered ref_group/reference +#' @return A `PreDataTableLayouts` object suitable for passing to further layouting functions, and to [build_table()]. #' -#' @export +#' @inheritSection custom_split_funs Custom Splitting Function Details #' -#' @author Gabriel Becker -#' @return A \code{PreDataTableLayouts} object suitable for passing to further -#' layouting functions, and to \code{build_table}. #' @examples #' lyt <- basic_table() %>% #' split_cols_by("ARM") %>% @@ -301,6 +307,7 @@ setMethod( #' #' # By default sequentially adding layouts results in nesting #' library(dplyr) +#' #' DM_MF <- DM %>% #' filter(SEX %in% c("M", "F")) %>% #' mutate(SEX = droplevels(SEX)) @@ -339,6 +346,8 @@ setMethod( #' tbl5 <- build_table(lyt5, DM) #' tbl5 #' +#' @author Gabriel Becker +#' @export split_cols_by <- function(lyt, var, labels_var = var, @@ -373,8 +382,10 @@ split_cols_by <- function(lyt, split_cols(lyt, spl, pos) } +## .tl_indent ==== setGeneric(".tl_indent_inner", function(lyt) standardGeneric(".tl_indent_inner")) + setMethod( ".tl_indent_inner", "PreDataTableLayouts", function(lyt) .tl_indent_inner(rlayout(lyt)) @@ -397,7 +408,6 @@ setMethod( } ) ## length(lyt) - 1L) - .tl_indent <- function(lyt, nested = TRUE) { if (!nested) { 0L @@ -406,25 +416,19 @@ setMethod( } } - -#' Add Rows according to levels of a variable -#' +#' Add rows according to levels of a variable #' -#' @inheritSection custom_split_funs Custom Splitting Function Details +#' @inheritParams lyt_args #' +#' @inherit split_cols_by return #' -#' @inheritParams lyt_args +#' @inheritSection custom_split_funs Custom Splitting Function Details #' #' @note -#' If \code{var} is a factor with empty unobserved levels and -#' \code{labels_var} is specified, it must also be a factor -#' with the same number of levels as \code{var}. Currently the -#' error that occurs when this is not the case is not very informative, -#' but that will change in the future. +#' If `var` is a factor with empty unobserved levels and `labels_var` is specified, it must also be a factor +#' with the same number of levels as `var`. Currently the error that occurs when this is not the case is not very +#' informative, but that will change in the future. #' -#' @export -#' @author Gabriel Becker -#' @inherit split_cols_by return #' @examples #' lyt <- basic_table() %>% #' split_cols_by("ARM") %>% @@ -456,6 +460,7 @@ setMethod( #' lyt3 #' #' library(dplyr) +#' #' DM2 <- DM %>% #' filter(SEX %in% c("M", "F")) %>% #' mutate( @@ -480,6 +485,8 @@ setMethod( #' tbl3 <- build_table(lyt3, DM2) #' tbl3 #' +#' @author Gabriel Becker +#' @export split_rows_by <- function(lyt, var, labels_var = var, @@ -516,24 +523,21 @@ split_rows_by <- function(lyt, ret } - -#' Associate Multiple Variables with Columns +#' Associate multiple variables with columns #' -#' In some cases, the variable to be ultimately analyzed is most naturally -#' defined on a column, not a row basis. When we need columns to reflect -#' different variables entirely, rather than different levels of a single -#' variable, we use `split_cols_by_multivar` +#' In some cases, the variable to be ultimately analyzed is most naturally defined on a column, not a row, basis. +#' When we need columns to reflect different variables entirely, rather than different levels of a single +#' variable, we use `split_cols_by_multivar`. #' #' @inheritParams lyt_args #' -#' @export -#' -#' @author Gabriel Becker +#' @inherit split_cols_by return #' #' @seealso [analyze_colvars()] -#' @inherit split_cols_by return +#' #' @examples #' library(dplyr) +#' #' ANL <- DM %>% mutate(value = rnorm(n()), pctdiff = runif(n())) #' #' ## toy example where we take the mean of the first variable and the @@ -557,6 +561,8 @@ split_rows_by <- function(lyt, #' tbl <- build_table(lyt, ANL) #' tbl #' +#' @author Gabriel Becker +#' @export split_cols_by_multivar <- function(lyt, vars, split_fun = NULL, @@ -575,17 +581,17 @@ split_cols_by_multivar <- function(lyt, split_cols(lyt, spl, pos) } -#' Associate Multiple Variables with Rows +#' Associate multiple variables with rows #' #' When we need rows to reflect different variables rather than different #' levels of a single variable, we use `split_rows_by_multivar`. #' #' @inheritParams lyt_args +#' #' @inherit split_rows_by return #' -#' @seealso [split_rows_by()] for typical row splitting, and -#' [split_cols_by_multivar()] to perform the same type of split on a column basis. -#' @export +#' @seealso [split_rows_by()] for typical row splitting, and [split_cols_by_multivar()] to perform the same type of +#' split on a column basis. #' #' @examples #' lyt <- basic_table() %>% @@ -597,6 +603,7 @@ split_cols_by_multivar <- function(lyt, #' tbl <- build_table(lyt, DM) #' tbl #' +#' @export split_rows_by_multivar <- function(lyt, vars, split_fun = NULL, @@ -626,29 +633,15 @@ split_rows_by_multivar <- function(lyt, #' Split on static or dynamic cuts of the data #' -#' Create columns (or row splits) based on values (such as quartiles) of -#' \code{var}. +#' Create columns (or row splits) based on values (such as quartiles) of `var`. #' #' @inheritParams lyt_args -#' @param cuts numeric. Cuts to use -#' @param cutlabels character (or NULL). Labels for the cuts -#' @param cumulative logical. Should the cuts be treated as cumulative. Defaults -#' to \code{FALSE} -#' @param cutfun function. Function which accepts the full vector of \code{var} -#' values and returns cut points to be passed to \code{cut}. -#' #' -#' @details For dynamic cuts, the cut is transformed into a static cut by -#' \code{\link{build_table}} \emph{based on the full dataset}, before -#' proceeding. Thus even when nested within another split in column/row space, -#' the resulting split will reflect the overall values (e.g., quartiles) in the -#' dataset, NOT the values for subset it is nested under. +#' @details For dynamic cuts, the cut is transformed into a static cut by [build_table()] *based on the full dataset*, +#' before proceeding. Thus even when nested within another split in column/row space, the resulting split will reflect +#' the overall values (e.g., quartiles) in the dataset, NOT the values for subset it is nested under. #' -#' @export -#' -#' @rdname varcuts #' @inherit split_cols_by return -#' @author Gabriel Becker #' #' @examples #' library(dplyr) @@ -731,6 +724,9 @@ split_rows_by_multivar <- function(lyt, #' tbl6 <- build_table(lyt6, ex_adsl) #' tbl6 #' +#' @author Gabriel Becker +#' @export +#' @rdname varcuts split_cols_by_cuts <- function(lyt, var, cuts, cutlabels = NULL, split_label = var, @@ -833,7 +829,6 @@ split_cols_by_quartiles <- function(lyt, var, split_label = var, ## split_cols(lyt, spl, pos) } - #' @export #' @rdname varcuts split_rows_by_quartiles <- function(lyt, var, split_label = var, @@ -883,8 +878,6 @@ split_rows_by_quartiles <- function(lyt, var, split_label = var, ## split_rows(lyt, spl, pos) } - - qtile_cuts <- function(x) { ret <- quantile(x) names(ret) <- c( @@ -930,179 +923,123 @@ split_rows_by_cutfun <- function(lyt, var, split_rows(lyt, spl, pos) } - -#' @title .spl_context within analysis and split functions -#' -#' @description -#' `.spl_context` is an optional parameter for any of `rtables`' special -#' functions, them being `afun` (analysis function in [analyze]), -#' `cfun` (content or label function in [summarize_row_groups]), -#' or `split_fun` (e.g. for [split_rows_by]). +#' .spl_context within analysis and split functions #' +#' `.spl_context` is an optional parameter for any of rtables' special functions, i.e. `afun` (analysis function +#' in [analyze()]), `cfun` (content or label function in [summarize_row_groups()]), or `split_fun` (e.g. for +#' [split_rows_by()]). #' #' @details -#' The `.spl_context` `data.frame` gives information about the subsets of data -#' corresponding to the splits within-which the current `analyze` action is -#' nested. Taken together, these correspond to the path that the resulting (set -#' of) rows the analysis function is creating, although the information is in a -#' slightly different form. Each split (which correspond to groups of rows in -#' the resulting table), as well as the initial 'root' "split", is represented +#' The `.spl_context` `data.frame` gives information about the subsets of data corresponding to the splits within +#' which the current `analyze` action is nested. Taken together, these correspond to the path that the resulting (set +#' of) rows the analysis function is creating, although the information is in a slightly different form. Each split +#' (which correspond to groups of rows in the resulting table), as well as the initial 'root' "split", is represented #' via the following columns: +#' #' \describe{ -#' \item{split}{The name of the split (often the variable being split in the -#' simple case)} -#' \item{value}{The string representation of the value at that split} -#' \item{full_parent_df}{a dataframe containing the full data (i.e. across all -#' columns) corresponding to the path defined by the combination of `split` -#' and `value` of this row \emph{and all rows above this row}} -#' \item{all_cols_n}{the number of observations corresponding to this row -#' grouping (union of all columns)} -#' \item{\emph{(row-split and analyze contexts only)} <1 column for each -#' column in the table structure}{ These list columns (named the same as -#' \code{names(col_exprs(tab))}) contain logical vectors corresponding to -#' the subset of this row's `full_parent_df` corresponding to that column} -#' \item{cur_col_id}{Identifier of the current column. This may be an internal -#' name, constructed by pasting the column path together} -#' \item{cur_col_subset}{List column containing logical vectors indicating the -#' subset of that row's `full_parent_df` for the column currently being -#' created by the analysis function} -#' \item{cur_col_expr}{List of current column expression. This may be used to -#' filter `.alt_df_row` or any external data by column. Filtering `.alt_df_row` -#' by columns produces `.alt_df`.} -#' \item{cur_col_n}{integer column containing the observation counts for that -#' split} -#' \item{cur_col_split}{Current column split names. This is recovered from the -#' current column path} -#' \item{cur_col_split_val}{Current column split values. This is recovered from the -#' current column path} +#' \item{split}{The name of the split (often the variable being split).} +#' \item{value}{The string representation of the value at that split (`split`).} +#' \item{full_parent_df}{A `data.frame` containing the full data (i.e. across all columns) corresponding to the path +#' defined by the combination of `split` and `value` of this row *and all rows above this row*.} +#' \item{all_cols_n}{The number of observations corresponding to the row grouping (union of all columns).} +#' \item{column for each column in the table structure (*row-split and analyze contexts only*)}{These list columns +#' (named the same as `names(col_exprs(tab))`) contain logical vectors corresponding to the subset of this row's +#' `full_parent_df` corresponding to the column.} +#' \item{cur_col_id}{Identifier of the current column. This may be an internal name, constructed by pasting the +#' column path together.} +#' \item{cur_col_subset}{List column containing logical vectors indicating the subset of this row's `full_parent_df` +#' for the column currently being created by the analysis function.} +#' \item{cur_col_expr}{List of current column expression. This may be used to filter `.alt_df_row`, or any external +#' data, by column. Filtering `.alt_df_row` by columns produces `.alt_df`.} +#' \item{cur_col_n}{Integer column containing the observation counts for that split.} +#' \item{cur_col_split}{Current column split names. This is recovered from the current column path.} +#' \item{cur_col_split_val}{Current column split values. This is recovered from the current column path.} #' } #' -#' \emph{note Within analysis functions that accept `.spl_context`, the -#' `all_cols_n` and `cur_col_n` columns of the dataframe will contain the 'true' -#' observation counts corresponding to the row-group and row-group x column -#' subsets of the data. These numbers will not, and currently cannot, reflect -#' alternate column observation counts provided by the `alt_counts_df`, -#' `col_counts` or `col_total` arguments to \code{\link{build_table}}} +#' @note +#' Within analysis functions that accept `.spl_context`, the `all_cols_n` and `cur_col_n` columns of the data frame +#' will contain the 'true' observation counts corresponding to the row-group and row-group x column subsets of the +#' data. These numbers will not, and currently cannot, reflect alternate column observation counts provided by the +#' `alt_counts_df`, `col_counts` or `col_total` arguments to [build_table()]. #' #' @name spl_context NULL -#' @title Additional parameters within analysis and content functions -#' (`afun/cfun`) +#' Additional parameters within analysis and content functions (`afun`/`cfun`) #' #' @description -#' It is possible to add specific parameters to `afun` and `cfun`, in [analyze] -#' and [summarize_row_groups] respectively. These parameters grant access to -#' relevant information like the row split structure (see [spl_context]) and the -#' predefined baseline (`.ref_group`). +#' It is possible to add specific parameters to `afun` and `cfun`, in [analyze()] and [summarize_row_groups()], +#' respectively. These parameters grant access to relevant information like the row split structure (see +#' [spl_context]) and the predefined baseline (`.ref_group`). #' #' @details -#' We list and describe here all the parameters that can be added to a custom -#' analysis function: +#' We list and describe all the parameters that can be added to a custom analysis function below: #' #' \describe{ -#' \item{.N_col}{column-wise N (column count) for the full column being -#' tabulated within} -#' \item{.N_total}{overall N (all observation count, defined as sum of column -#' counts) for the tabulation} -#' \item{.N_row}{row-wise N (row group count) for the group of observations -#' being analyzed (i.e. with no column-based subsetting)} -#' \item{.df_row}{data.frame for observations in the row group being analyzed -#' (i.e. with no column-based subsetting)} -#' \item{.var}{variable that is analyzed} -#' \item{.ref_group}{data.frame or vector of subset corresponding to the -#' `ref_group` column including subsetting defined by row-splitting. -#' Optional and only required/meaningful if a `ref_group` column has been -#' defined} -#' \item{.ref_full}{data.frame or vector of subset corresponding to the -#' `ref_group` column without subsetting defined by row-splitting. Optional -#' and only required/meaningful if a `ref_group` column has been defined} -#' \item{.in_ref_col}{boolean indicates if calculation is done for cells -#' within the reference column} -#' \item{.spl_context}{data.frame, each row gives information about a -#' previous/'ancestor' split state. See \code{\link{spl_context}}} -#' \item{.alt_df_row}{data.frame, i.e. the `alt_count_df` after -#' row splitting. It can be used with `.all_col_exprs` and `.spl_context` -#' information to retrieve current faceting, but for `alt_count_df`. +#' \item{.N_col}{Column-wise N (column count) for the full column being tabulated within.} +#' \item{.N_total}{Overall N (all observation count, defined as sum of column counts) for the tabulation.} +#' \item{.N_row}{Row-wise N (row group count) for the group of observations being analyzed (i.e. with no +#' column-based subsetting).} +#' \item{.df_row}{`data.frame` for observations in the row group being analyzed (i.e. with no column-based +#' subsetting).} +#' \item{.var}{Variable being analyzed.} +#' \item{.ref_group}{`data.frame` or vector of subset corresponding to the `ref_group` column including subsetting +#' defined by row-splitting. Only required/meaningful if a `ref_group` column has been defined.} +#' \item{.ref_full}{`data.frame` or vector of subset corresponding to the `ref_group` column without subsetting +#' defined by row-splitting. Only required/meaningful if a `ref_group` column has been defined.} +#' \item{.in_ref_col}{Boolean indicating if calculation is done for cells within the reference column.} +#' \item{.spl_context}{`data.frame` where each row gives information about a previous 'ancestor' split state. +#' See [spl_context].} +#' \item{.alt_df_row}{`data.frame`, i.e. the `alt_count_df` after row splitting. It can be used with +#' `.all_col_exprs` and `.spl_context` information to retrieve current faceting, but for `alt_count_df`. #' It can be an empty table if all the entries are filtered out.} -#' \item{.alt_df}{data.frame, `.alt_df_row` but filtered by columns expression. -#' This data present the same faceting of main data `df`. This also filters -#' `NAs` out if related parameters are set to (e.g. `inclNAs` in [analyze]). -#' Similarly to `.alt_df_row`, it can be an empty table if all the entries -#' are filtered out.} -#' \item{.all_col_exprs}{list of expressions. Each of them represents a -#' different column splitting.} -#' \item{.all_col_counts}{vector of integers. Each of them represents the global -#' count for each column. It differs if `alt_counts_df` is used -#' (see [build_table]).} +#' \item{.alt_df}{`data.frame`, `.alt_df_row` but filtered by columns expression. This data present the same +#' faceting of main data `df`. This also filters `NA`s out if related parameters are set to do so (e.g. `inclNAs` +#' in [analyze()]). Similarly to `.alt_df_row`, it can be an empty table if all the entries are filtered out.} +#' \item{.all_col_exprs}{List of expressions. Each of them represents a different column splitting.} +#' \item{.all_col_counts}{Vector of integers. Each of them represents the global count for each column. It differs +#' if `alt_counts_df` is used (see [build_table()]).} #' } #' -#' @note If any of these formals is specified incorrectly or not -#' present in the tabulation machinery, it will be as if missing. For -#' example`.ref_group` will be missing if no baseline is previously defined -#' during data splitting (via `ref_group` parameters in, e.g., [split_rows_by]). -#' Similarly, if no `alt_counts_df` is provided into [build_table], -#' `.alt_df_row` and `.alt_df` will not be present. +#' @note If any of these formals is specified incorrectly or not present in the tabulation machinery, it will be +#' treated as if missing. For example, `.ref_group` will be missing if no baseline is previously defined during +#' data splitting (via `ref_group` parameters in, e.g., [split_rows_by()]). Similarly, if no `alt_counts_df` is +#' provided to [build_table()], `.alt_df_row` and `.alt_df` will not be present. #' #' @name additional_fun_params NULL -#' Generate Rows Analyzing Variables Across Columns +#' Generate rows analyzing variables across columns #' -#' Adding *analyzed variables* to our table layout defines the primary -#' tabulation to be performed. We do this by adding calls to \code{analyze} -#' and/or \code{\link{analyze_colvars}} into our layout pipeline. As with adding -#' further splitting, the tabulation will occur at the current/next level of -#' nesting by default. +#' Adding *analyzed variables* to our table layout defines the primary tabulation to be performed. We do this by +#' adding calls to `analyze` and/or [analyze_colvars()] into our layout pipeline. As with adding further splitting, +#' the tabulation will occur at the current/next level of nesting by default. #' #' @inheritParams lyt_args #' #' @inherit split_cols_by return #' #' @details +#' When non-`NULL`, `format` is used to specify formats for all generated rows, and can be a character vector, a +#' function, or a list of functions. It will be repped out to the number of rows once this is calculated during the +#' tabulation process, but will be overridden by formats specified within `rcell` calls in `afun`. #' -#' When non-NULL \code{format} is used to specify formats for all generated -#' rows, and can be a character vector, a function, or a list of functions. It -#' will be repped out to the number of rows once this is known during the -#' tabulation process, but will be overridden by formats specified within -#' \code{rcell} calls in \code{afun}. -#' -#' The analysis function (\code{afun}) should take as its first parameter either -#' \code{x} or \code{df}. Which of these the function accepts changes the -#' behavior when tabulation is performed. -#' -#' \itemize{ -#' \item{ -#' If \code{afun}'s first parameter is x, it will receive the corresponding -#' subset \emph{vector} of data from the relevant column (from \code{var} -#' here) of the raw data being used to build the table. -#' } -#' -#' \item{ -#' If \code{afun}'s first parameter is \code{df}, it will receive the -#' corresponding subset \emph{data.frame} (i.e. all columns) of the raw data -#' being tabulated -#' } -#' } -#' -#' In addition to differentiation on the first argument, the analysis function -#' can optionally accept a number of other parameters which, \emph{if and only -#' if} present in the formals will be passed to the function by the tabulation -#' machinery. These are listed and described in [`additional_fun_params`]. -#' -#' @note None of the arguments described in the Details section -#' can be overridden via \code{extra_args} or when calling -#' \code{\link{make_afun}}. \code{.N_col} and \code{.N_total} can -#' be overridden via the \code{col_counts} argument to -#' \code{\link{build_table}}. Alternative values for the others -#' must be calculated within \code{afun} based on a combination -#' of extra arguments and the unmodified values provided by the -#' tabulation framework. +#' The analysis function (`afun`) should take as its first parameter either `x` or `df`. Whichever of these the +#' function accepts will change the behavior when tabulation is performed as follows: #' -#' @export +#' - If `afun`'s first parameter is `x`, it will receive the corresponding subset *vector* of data from the relevant +#' column (from `var` here) of the raw data being used to build the table. +#' - If `afun`'s first parameter is `df`, it will receive the corresponding subset *data frame* (i.e. all columns) of +#' the raw data being tabulated. #' -#' @author Gabriel Becker +#' In addition to differentiation on the first argument, the analysis function can optionally accept a number of +#' other parameters which, *if and only if* present in the formals, will be passed to the function by the tabulation +#' machinery. These are listed and described in [additional_fun_params]. #' +#' @note None of the arguments described in the Details section can be overridden via `extra_args` or when calling +#' [make_afun()]. `.N_col` and `.N_total` can be overridden via the `col_counts` argument to [build_table()]. +#' Alternative values for the others must be calculated within `afun` based on a combination of extra arguments and +#' the unmodified values provided by the tabulation framework. #' #' @examples #' lyt <- basic_table() %>% @@ -1126,6 +1063,8 @@ NULL #' tbl2 <- build_table(lyt2, iris) #' tbl2 #' +#' @author Gabriel Becker +#' @export analyze <- function(lyt, vars, afun = simple_analysis, @@ -1134,7 +1073,7 @@ analyze <- function(lyt, format = NULL, na_str = NA_character_, nested = TRUE, - ## can't name this na_rmsymbol conflict with possible afuns!! + ## can't name this na_rm symbol conflict with possible afuns!! inclNAs = FALSE, extra_args = list(), show_labels = c("default", "visible", "hidden"), @@ -1185,8 +1124,6 @@ analyze <- function(lyt, } } - - get_acolvar_name <- function(lyt) { ## clyt <- clayout(lyt) ## stopifnot(length(clyt) == 1L) @@ -1196,7 +1133,6 @@ get_acolvar_name <- function(lyt) { paste(c("ac", get_acolvar_vars(lyt)), collapse = "_") } - get_acolvar_vars <- function(lyt) { clyt <- clayout(lyt) stopifnot(length(clyt) == 1L) @@ -1210,27 +1146,21 @@ get_acolvar_vars <- function(lyt) { } } - -#' Generate Rows Analyzing Different Variables Across Columns -#' -#' @inheritParams lyt_args -#' -#' @param afun function or list. Function(s) to be used to calculate the values -#' in each column. The list will be repped out as needed and matched by -#' position with the columns during tabulation. This functions accepts the same -#' parameters as [analyze] like `afun` and `format`. For further information see -#' [`additional_fun_params`]. +#' Generate rows analyzing different variables across columns #' -#' @export +#' @inheritParams lyt_args +#' @param afun (`function` or `list`)\cr function(s) to be used to calculate the values in each column. The list +#' will be repped out as needed and matched by position with the columns during tabulation. This functions +#' accepts the same parameters as [analyze()] like `afun` and `format`. For further information see +#' [additional_fun_params]. #' #' @inherit split_cols_by return #' #' @seealso [split_cols_by_multivar()] #' -#' @author Gabriel Becker -#' #' @examples #' library(dplyr) +#' #' ANL <- DM %>% mutate(value = rnorm(n()), pctdiff = runif(n())) #' #' ## toy example where we take the mean of the first variable and the @@ -1269,6 +1199,8 @@ get_acolvar_vars <- function(lyt) { #' tbl2 <- build_table(lyt2, ANL) #' tbl2 #' +#' @author Gabriel Becker +#' @export analyze_colvars <- function(lyt, afun, format = NULL, @@ -1324,20 +1256,15 @@ analyze_colvars <- function(lyt, ## Add a total column at the next **top level** spot in ## the column layout. -#' Add Overall Column +#' Add overall column #' -#' @description This function will \emph{only} add an overall -#' column at the \emph{top} level of splitting, NOT within -#' existing column splits. -#' See \code{\link{add_overall_level}} for the recommended -#' way to add overall columns more generally within existing splits. +#' This function will *only* add an overall column at the *top* level of splitting, NOT within existing column splits. +#' See [add_overall_level()] for the recommended way to add overall columns more generally within existing splits. #' #' @inheritParams lyt_args #' #' @inherit split_cols_by return #' -#' @export -#' #' @seealso [add_overall_level()] #' #' @examples @@ -1350,6 +1277,7 @@ analyze_colvars <- function(lyt, #' tbl <- build_table(lyt, DM) #' tbl #' +#' @export add_overall_col <- function(lyt, label) { spl <- AllSplit(label) split_cols( @@ -1359,9 +1287,10 @@ add_overall_col <- function(lyt, label) { ) } +## add_row_summary ==== -#' #' @inheritParams lyt_args +#' #' @export #' #' @rdname int_methods @@ -1405,6 +1334,7 @@ setMethod( lyt } ) + #' @rdname int_methods setMethod( ".add_row_summary", "PreDataRowLayout", @@ -1446,6 +1376,7 @@ setMethod( lyt } ) + #' @rdname int_methods setMethod( ".add_row_summary", "SplitVector", @@ -1478,6 +1409,7 @@ setMethod( lyt } ) + #' @rdname int_methods setMethod( ".add_row_summary", "Split", @@ -1573,13 +1505,15 @@ setMethod( #' Analysis function to count levels of a factor with percentage of the column total #' -#' @param x factor. Vector of data, provided by rtables pagination machinery -#' @param .N_col integer(1). Total count for the column, provided by rtables pagination machinery +#' @param x (`factor`)\cr a vector of data, provided by rtables pagination machinery. +#' @param .N_col (`integer(1)`)\cr total count for the column, provided by rtables pagination machinery. +#' +#' @return A `RowsVerticalSection` object with counts (and percents) for each level of the factor. #' -#' @return A `RowsVerticalSection` object with counts (and percents) for each level of the factor -#' @export #' @examples #' counts_wpcts(DM$SEX, 400) +#' +#' @export counts_wpcts <- function(x, .N_col) { if (!is.factor(x)) { stop( @@ -1598,25 +1532,19 @@ counts_wpcts <- function(x, .N_col) { #' #' @inherit split_cols_by return #' -#' @details If `format` expects 1 value (i.e. it is specified as a format string -#' and `xx` appears for two values (i.e. `xx` appears twice in the -#' format string) or is specified as a function, then both raw and percent of -#' column total counts are calculated. If `format` is a format string where -#' `xx` appears only one time, only raw counts are used. -#' -#' `cfun` must accept `x` or `df` as its first argument. For the `df` argument -#' `cfun` will receive the subset `data.frame` corresponding with the row- -#' and column-splitting for the cell being calculated. Must accept `labelstr` as -#' the second parameter, which accepts the `label` of the level of the parent -#' split currently being summarized. Can additionally take any optional argument -#' supported by analysis functions. (see \code{\link{analyze}}). +#' @details +#' If `format` expects 1 value (i.e. it is specified as a format string and `xx` appears for two values +#' (i.e. `xx` appears twice in the format string) or is specified as a function, then both raw and percent of +#' column total counts are calculated. If `format` is a format string where `xx` appears only one time, only +#' raw counts are used. #' -#' In addition, if complex custom functions are needed, we suggest checking the -#' available [additional_fun_params] that apply here as for `afun`. +#' `cfun` must accept `x` or `df` as its first argument. For the `df` argument `cfun` will receive the subset +#' `data.frame` corresponding with the row- and column-splitting for the cell being calculated. Must accept +#' `labelstr` as the second parameter, which accepts the `label` of the level of the parent split currently +#' being summarized. Can additionally take any optional argument supported by analysis functions. (see [analyze()]). #' -#' @export -#' -#' @author Gabriel Becker +#' In addition, if complex custom functions are needed, we suggest checking the available [additional_fun_params] +#' that can be used in `cfun`. #' #' @examples #' DM2 <- subset(DM, COUNTRY %in% c("USA", "CAN", "CHN")) @@ -1633,7 +1561,6 @@ counts_wpcts <- function(x, .N_col) { #' #' row_paths_summary(tbl) # summary count is a content table #' -#' #' ## use a cfun and extra_args to customize summarization #' ## behavior #' sfun <- function(x, labelstr, trim) { @@ -1660,6 +1587,8 @@ counts_wpcts <- function(x, .N_col) { #' tbl2 <- build_table(lyt2, DM2) #' tbl2 #' +#' @author Gabriel Becker +#' @export summarize_row_groups <- function(lyt, var = "", label_fstr = "%s", @@ -1686,26 +1615,19 @@ summarize_row_groups <- function(lyt, ) } - #' Add the column population counts to the header #' #' Add the data derived column counts. #' #' @details It is often the case that the the column counts derived from the -#' input data to `build_table` is not representative of the population counts. +#' input data to [build_table()] is not representative of the population counts. #' For example, if events are counted in the table and the header should -#' display the number of subjects and not the total number of events. In that -#' case use the `col_count` argument in `build_table` to control the counts -#' displayed in the table header. +#' display the number of subjects and not the total number of events. #' #' @inheritParams lyt_args #' #' @inherit split_cols_by return #' -#' @export -#' -#' @author Gabriel Becker -#' #' @examples #' lyt <- basic_table() %>% #' split_cols_by("ARM") %>% @@ -1717,6 +1639,8 @@ summarize_row_groups <- function(lyt, #' tbl <- build_table(lyt, DM) #' tbl #' +#' @author Gabriel Becker +#' @export add_colcounts <- function(lyt, format = "(N=xx)") { if (is.null(lyt)) { lyt <- PreDataTableLayouts() @@ -1726,16 +1650,13 @@ add_colcounts <- function(lyt, format = "(N=xx)") { lyt } -## Currently existing tables can ONLY be added -## as new entries at the top level, never at any -## level of nesting. +## Currently existing tables can ONLY be added as new entries at the top level, never at any level of nesting. #' Add an already calculated table to the layout +#' #' @inheritParams lyt_args #' @inheritParams gen_args #' #' @inherit split_cols_by return -#' @export -#' @author Gabriel Becker #' #' @examples #' lyt1 <- basic_table() %>% @@ -1756,6 +1677,8 @@ add_colcounts <- function(lyt, format = "(N=xx)") { #' table_structure(tbl2) #' row_paths_summary(tbl2) #' +#' @author Gabriel Becker +#' @export add_existing_table <- function(lyt, tt, indent_mod = 0) { indent_mod(tt) <- indent_mod lyt <- split_rows( @@ -1766,7 +1689,6 @@ add_existing_table <- function(lyt, tt, indent_mod = 0) { lyt } - ## takes_coln = function(f) { ## stopifnot(is(f, "function")) ## forms = names(formals(f)) @@ -1781,12 +1703,13 @@ add_existing_table <- function(lyt, tt, indent_mod = 0) { ## res ## } - ## use data to transform dynamic cuts to static cuts #' @rdname int_methods setGeneric("fix_dyncuts", function(spl, df) standardGeneric("fix_dyncuts")) + #' @rdname int_methods setMethod("fix_dyncuts", "Split", function(spl, df) spl) + #' @rdname int_methods setMethod( "fix_dyncuts", "VarDynCutSplit", @@ -1816,18 +1739,19 @@ setMethod( ret } ) + #' @rdname int_methods setMethod( "fix_dyncuts", "VTableTree", function(spl, df) spl ) - .fd_helper <- function(spl, df) { lst <- lapply(spl, fix_dyncuts, df = df) spl@.Data <- lst spl } + #' @rdname int_methods setMethod( "fix_dyncuts", "PreDataRowLayout", @@ -1838,6 +1762,7 @@ setMethod( ret } ) + #' @rdname int_methods setMethod( "fix_dyncuts", "PreDataColLayout", @@ -1850,6 +1775,7 @@ setMethod( ret } ) + #' @rdname int_methods setMethod( "fix_dyncuts", "SplitVector", @@ -1857,6 +1783,7 @@ setMethod( .fd_helper(spl, df) } ) + #' @rdname int_methods setMethod( "fix_dyncuts", "PreDataTableLayouts", @@ -1867,22 +1794,15 @@ setMethod( } ) - - - -## Manual column construction in a simple (seeming -## to the user) way. +## Manual column construction in a simple (seeming to the user) way. #' Manual column declaration -#' @param \dots One or more vectors of levels to appear in the column space. If -#' more than one set of levels is given, the values of the second are nested -#' within each value of the first, and so on. -#' @param .lst A list of sets of levels, by default populated via -#' \code{list(...)}. -#' @return An `InstantiatedColumnInfo` object, suitable for use declaring the -#' column structure for a manually constructed table. -#' @author Gabriel Becker #' -#' @export +#' @param ... one or more vectors of levels to appear in the column space. If more than one set of levels is given, +#' the values of the second are nested within each value of the first, and so on. +#' @param .lst (`list`)\cr a list of sets of levels, by default populated via `list(...)`. +#' +#' @return An `InstantiatedColumnInfo` object, suitable for declaring the column structure for a manually constructed +#' table. #' #' @examples #' # simple one level column space @@ -1902,6 +1822,8 @@ setMethod( #' ) #' tbl2 #' +#' @author Gabriel Becker +#' @export manual_cols <- function(..., .lst = list(...)) { if (is.null(names(.lst))) { names(.lst) <- paste("colsplit", seq_along(.lst)) @@ -1915,26 +1837,20 @@ manual_cols <- function(..., .lst = list(...)) { InstantiatedColumnInfo(treelyt = ctree) } - -#' Returns a function that coerces the return values of f to a list +#' Returns a function that coerces the return values of a function to a list #' -#' @param f The function to wrap. -#' @export +#' @param f (`function`)\cr the function to wrap. +#' +#' @details +#' `list_wrap_x` generates a wrapper which takes `x` as its first argument, while `list_wrap_df` generates an +#' otherwise identical wrapper function whose first argument is named `df`. #' -#' @details \code{list_wrap_x} generates a wrapper which takes \code{x} as its -#' first argument, while \code{list_wrap_df} generates an otherwise identical -#' wrapper function whose first argument is named \code{df}. +#' We provide both because when using the functions as tabulation in [analyze()], functions which take `df` as +#' their first argument are passed the full subset data frame, while those which accept anything else notably +#' including `x` are passed only the relevant subset of the variable being analyzed. #' -#' We provide both because when using the functions as tabulation in -#' \code{\link{analyze}}, functions which take \code{df} as their first -#' argument are passed the full subset dataframe, while those which accept -#' anything else notably including \code{x} are passed only the relevant -#' subset of the variable being analyzed. +#' @return A function that returns a list of `CellValue` objects. #' -#' @rdname list_wrap -#' @return A function which calls \code{f} and converts the result to a list of -#' \code{CellValue} objects. -#' @author Gabriel Becker #' @examples #' summary(iris$Sepal.Length) #' @@ -1944,6 +1860,9 @@ manual_cols <- function(..., .lst = list(...)) { #' f2 <- list_wrap_df(summary) #' f2(df = iris$Sepal.Length) #' +#' @author Gabriel Becker +#' @rdname list_wrap +#' @export list_wrap_x <- function(f) { function(x, ...) { vs <- as.list(f(x, ...)) @@ -1974,43 +1893,36 @@ list_wrap_df <- function(f) { } } - #' Layout with 1 column and zero rows #' #' Every layout must start with a basic table. #' #' @inheritParams constr_args -#' @param show_colcounts logical(1). Should column counts be displayed in the -#' resulting table when this layout is applied to data -#' @param colcount_format character(1). Format for use when displaying the -#' column counts. Must be 1d, or 2d where one component is a percent. See -#' details. -#' @param top_level_section_div character(1). If assigned to a single character, -#' the first (top level) split or division of the table will be highlighted by a line made of that character. -#' See [section_div] for more information. +#' @param show_colcounts (`flag`)\cr whether column counts should be displayed in the resulting table when this +#' layout is applied to data. +#' @param colcount_format (`string`)\cr format for use when displaying the column counts. Must be 1d, or 2d +#' where one component is a percent. See Details below. +#' @param top_level_section_div (`character(1)`)\cr if assigned a single character, the first (top level) split +#' or division of the table will be highlighted by a line made of that character. See [section_div] for more +#' information. #' #' @details -#' `colcount_format` is ignored if `show_colcounts` is `FALSE` (the default). -#' When `show_colcounts` is `TRUE`, and `colcount_format` is 2-dimensional with -#' a percent component, the value component for the percent is always populated -#' with `1` (i.e. 100%). 1d formats are used to render the counts exactly as they -#' normally would be, while 2d formats which don't include a percent, and all 3d -#' formats result in an error. Formats in the form of functions are not supported for -#' `colcount` format. See [formatters::list_valid_format_labels()] for -#' the list of valid format labels to select from. +#' `colcount_format` is ignored if `show_colcounts` is `FALSE` (the default). When `show_colcounts` is `TRUE`, +#' and `colcount_format` is 2-dimensional with a percent component, the value component for the percent is always +#' populated with `1` (i.e. 100%). 1d formats are used to render the counts exactly as they normally would be, +#' while 2d formats which don't include a percent, and all 3d formats result in an error. Formats in the form of +#' functions are not supported for `colcount` format. See [formatters::list_valid_format_labels()] for the list +#' of valid format labels to select from. #' #' @inherit split_cols_by return #' #' @note -#' - Because percent components in `colcount_format` are *always* -#' populated with the value 1, we can get arguably strange results, such as -#' that individual arm columns and a combined "all patients" column all -#' list "100%" as their percentage, even though the individual arm columns -#' represent strict subsets of the all patients column. +#' - Because percent components in `colcount_format` are *always* populated with the value 1, we can get arguably +#' strange results, such as that individual arm columns and a combined "all patients" column all list "100%" as +#' their percentage, even though the individual arm columns represent strict subsets of the "all patients" column. #' -#' - Note that subtitles ([subtitles()]) and footers ([main_footer()] and [prov_footer()]) -#' that spans more than one line can be supplied as a character vector to maintain -#' indentation on multiple lines. +#' - Note that subtitles ([subtitles()]) and footers ([main_footer()] and [prov_footer()]) that span more than one +#' line can be supplied as a character vector to maintain indentation on multiple lines. #' #' @examples #' lyt <- basic_table() %>% @@ -2072,32 +1984,28 @@ basic_table <- function(title = "", ret } - #' Append a description to the 'top-left' materials for the layout #' -#' @description This function \emph{adds} \code{newlines} to the current -#' set of "top-left materials". +#' This function *adds* `newlines` to the current set of "top-left materials". +#' #' @details +#' Adds `newlines` to the set of strings representing the 'top-left' materials declared in the layout (the content +#' displayed to the left of the column labels when the resulting tables are printed). #' -#' Adds \code{newlines} to the set of strings representing the 'top-left' -#' materials declared in the layout (the content displayed to the left of -#' the column labels when the resulting tables are printed). +#' Top-left material strings are stored and then displayed *exactly as is*, no structure or indenting is applied to +#' them either when they are added or when they are displayed. #' -#' Top-left material strings are stored and then displayed \emph{exactly as is}, -#' no structure or indenting is applied to them either when they are added -#' or when they are displayed. #' @inheritParams lyt_args +#' @param newlines (`character`)\cr the new line(s) to be added to the materials. #' -#' @inherit split_cols_by return +#' @note +#' Currently, where in the construction of the layout this is called makes no difference, as it is independent of +#' the actual splitting keywords. This may change in the future. #' -#' @param newlines character. The new line(s) to be added to the materials -#' @note Currently, where in the construction of the layout this is called -#' makes no difference, as it is independent of the actual splitting keywords. -#' This may change in the future. -#' @note This function is experimental, its name and the details of -#' its behavior are subject to change in future versions. +#' This function is experimental, its name and the details of its behavior are subject to change in future versions. +#' +#' @inherit split_cols_by return #' -#' @export #' @seealso [top_left()] #' #' @examples @@ -2116,6 +2024,7 @@ basic_table <- function(title = "", #' tbl <- build_table(lyt, DM2) #' tbl #' +#' @export append_topleft <- function(lyt, newlines) { stopifnot( is(lyt, "PreDataTableLayouts"), diff --git a/R/compare_rtables.R b/R/compare_rtables.R index be0719787..823f689b1 100644 --- a/R/compare_rtables.R +++ b/R/compare_rtables.R @@ -1,26 +1,25 @@ #' Compare two rtables #' -#' Prints a matrix where \code{.} means cell matches, \code{X} means cell does -#' cells do not match, \code{+} cell (row) is missing, and \code{-} cell (row) -#' should not be there. If `structure` is set to `TRUE`, \code{C} indicates -#' columnar structure mismatch, \code{R} indicates row-structure mismatch, and -#' \code{S} indicates mismatch in both row and column structure. +#' Prints a matrix where `.` means cell matches, `X` means cell does +#' not match, `+` cell (row) is missing, and `-` cell (row) +#' should not be there. If `structure` is set to `TRUE`, `C` indicates +#' column-structure mismatch, `R` indicates row-structure mismatch, and +#' `S` indicates mismatch in both row and column structure. #' -#' @param object `rtable` to test -#' @param expected `rtable` expected -#' @param tol numerical tolerance -#' @param comp.attr boolean. Compare format of cells. Other attributes are -#' silently ignored. -#' @param structure boolean. Should structure (in the form of column and row -#' paths to cells) be compared. Currently defaults to `FALSE`, but this is -#' subject to change in future versions. +#' @param object (`VTableTree`)\cr `rtable` to test. +#' @param expected (`VTableTree`)\cr expected `rtable`. +#' @param tol (`numeric(1)`)\cr tolerance. +#' @param comp.attr (`flag`)\cr whether to compare cell formats. Other attributes are +#' silently ignored. +#' @param structure (`flag`)\cr whether structures (in the form of column and row +#' paths to cells) should be compared. Currently defaults to `FALSE`, but this is +#' subject to change in future versions. #' -#' @note In its current form \code{compare_rtables} does not take structure into -#' account, only row and cell position. +#' @note In its current form, `compare_rtables` does not take structure into +#' account, only row and cell position. #' -#' @return a matrix of class \code{"rtables_diff"} representing the differences -#' between \code{object} and \code{expected} as described above. -#' @export +#' @return A matrix of class `rtables_diff` representing the differences +#' between `object` and `expected` as described above. #' #' @examples #' t1 <- rtable(header = c("A", "B"), format = "xx", rrow("row 1", 1, 2)) @@ -84,6 +83,8 @@ #' ) #' #' compare_rtables(object, expected) +#' +#' @export compare_rtables <- function(object, expected, tol = 0.1, comp.attr = TRUE, structure = FALSE) { # if (identical(object, expected)) return(invisible(TRUE)) @@ -149,7 +150,6 @@ compare_rtables <- function(object, expected, tol = 0.1, comp.attr = TRUE, ## from here dimensions match! - orows <- cell_values(object, omit_labrows = FALSE) erows <- cell_values(expected, omit_labrows = FALSE) if (nrow(object) == 1) { @@ -199,8 +199,6 @@ compare_rtables <- function(object, expected, tol = 0.1, comp.attr = TRUE, X } - - ## for (i in 1:dim(X)[1]) { ## for (j in 1:dim(X)[2]) { @@ -250,6 +248,7 @@ compare_value <- function(x, y, tol) { "X" } } + compare_rrows <- function(row1, row2, tol, ncol) { if (length(row1) == ncol && length(row2) == ncol) { mapply(compare_value, x = row1, y = row2, tol = tol, USE.NAMES = FALSE) diff --git a/R/deprecated.R b/R/deprecated.R deleted file mode 100644 index 45840cb61..000000000 --- a/R/deprecated.R +++ /dev/null @@ -1,44 +0,0 @@ -# nocov start -add_analyzed_var <- function(lyt, var, label = var, afun, - format = NULL, - rowlabs = "", - nested = FALSE, - inclNAs = FALSE) { - spl <- AnalyzeVarSplit(var, label, - afun = afun, - split_format = format, - defrowlab = rowlabs, - inclNAs = inclNAs - ) - .Deprecated("analyze") - - if (!nested && (is(last_rowsplit(lyt), "AnalyzeVarSplit") || is(last_rowsplit(lyt), "AnalyzeMultiVars"))) { - cmpnd_last_rowsplit(lyt, spl) - } else { - pos <- next_rpos(lyt, nested) - split_rows(lyt, spl, pos) - } -} - -#' Trim Zero Rows -#' -#' @param tbl table object -#' -#' @return an `rtable` object -#' -#' @export -trim_zero_rows <- function(tbl) { - .Deprecated( - new = "prune_table(tbl, all_zero) or prune_table(tbl, prune_zeros_only)", - old = "trim_zero_rows(tbl)" - ) - - stopifnot(is(tbl, "VTableTree")) - - rows <- collect_leaves(tbl, TRUE, TRUE) - torm <- vapply(rows, function(x) { - identical(unname(unlist(row_values(x))), rep(0L, ncol(tbl))) - }, NA, USE.NAMES = FALSE) - tbl[!torm, , keep_topleft = TRUE] -} -# nocov end diff --git a/R/format_rcell.R b/R/format_rcell.R index e3083840f..46eb8df9a 100644 --- a/R/format_rcell.R +++ b/R/format_rcell.R @@ -1,21 +1,18 @@ -#' Format `rcell` +#' Format `rcell` objects #' -#' This is a wrapper around -#' \code{\link[formatters:format_value]{formatters::format_value}} for use with -#' \code{CellValue} objects +#' This is a wrapper for [formatters::format_value()] for use with `CellValue` objects #' -#' @param x an object of class \code{\link{CellValue}}, or a raw value. -#' @param format character(1) or function. The format label (string) or -#' formatter function to apply to \code{x}. -#' @param output character(1). Output type. -#' @param na_str character(1). String that should be displayed when the value of -#' \code{x} is missing. Defaults to \code{"NA"}. -#' @param pr_row_format list of default format coming from the general row. -#' @param pr_row_na_str list of default \code{"NA"} string coming from the general row. -#' @param shell logical(1). Should the formats themselves be returned instead of the -#' values with formats applied. Defaults to \code{FALSE}. +#' @inheritParams lyt_args +#' @param x (`CellValue` or `ANY`)\cr an object of class `CellValue`, or a raw value. +#' @param format (`string` or `function`)\cr the format label or formatter function to +#' apply to `x`. +#' @param output (`string`)\cr output type. +#' @param pr_row_format (`list`)\cr list of default formats coming from the general row. +#' @param pr_row_na_str (`list`)\cr list of default `"NA"` strings coming from the general row. +#' @param shell (`flag`)\cr whether the formats themselves should be returned instead of the +#' values with formats applied. Defaults to `FALSE`. #' -#' @return formatted text representing the cell +#' @return Formatted text. #' #' @examples #' cll <- CellValue(pi, format = "xx.xxx") diff --git a/R/indent.R b/R/indent.R index 47859a4d9..8c1e60ccf 100644 --- a/R/indent.R +++ b/R/indent.R @@ -2,12 +2,12 @@ #' #' Change indentation of all `rrows` in an `rtable` #' -#' @param x \code{\link{rtable}} object -#' @param by integer to increase indentation of rows. Can be negative. If final indentation is smaller than 0 then the -#' indentation is set to 0. +#' @param x (`VTableTree`)\cr an `rtable` object. +#' @param by (`integer`)\cr number to increase indentation of rows by. Can be negative. If final indentation is +#' less than 0, the indentation is set to 0. +#' +#' @return `x` with its indent modifier incremented by `by`. #' -#' @export -#' @return \code{x} with its indent modifier incremented by \code{by}. #' @examples #' is_setosa <- iris$Species == "setosa" #' m_tbl <- rtable( @@ -31,6 +31,7 @@ #' indent(m_tbl) #' indent(m_tbl, 2) #' +#' @export indent <- function(x, by = 1) { if (nrow(x) == 0 || by == 0) { return(x) @@ -40,9 +41,12 @@ indent <- function(x, by = 1) { x } -#' Clear All Indent Mods from a Table +#' Clear all indent modifiers from a table +#' #' @inheritParams gen_args -#' @return The same class as \code{tt}, with all indent mods set to zero. +#' +#' @return The same class as `tt`, with all indent modifiers set to zero. +#' #' @examples #' lyt1 <- basic_table() %>% #' summarize_row_groups("STUDYID", label_fstr = "overall summary") %>% @@ -53,9 +57,11 @@ indent <- function(x, by = 1) { #' tbl1 <- build_table(lyt1, ex_adae) #' tbl1 #' clear_indent_mods(tbl1) +#' #' @export #' @rdname clear_imods setGeneric("clear_indent_mods", function(tt) standardGeneric("clear_indent_mods")) + #' @export #' @rdname clear_imods setMethod( @@ -70,6 +76,7 @@ setMethod( tt } ) + #' @export #' @rdname clear_imods setMethod( diff --git a/R/index_footnotes.R b/R/index_footnotes.R index fad316bda..16a268394 100644 --- a/R/index_footnotes.R +++ b/R/index_footnotes.R @@ -15,10 +15,8 @@ }) } - setGeneric(".idx_helper", function(tr, cur_idx_fun) standardGeneric(".idx_helper")) - setMethod( ".idx_helper", "TableRow", function(tr, cur_idx_fun) { @@ -61,7 +59,6 @@ index_col_refs <- function(tt, cur_idx_fun) { tt } - .index_col_refs_inner <- function(ctree, cur_idx_fun) { col_footnotes(ctree) <- .reindex_one_pos( col_footnotes(ctree), @@ -81,18 +78,19 @@ index_col_refs <- function(tt, cur_idx_fun) { ## function(refs) lapply(refs, function(refi) { } -#' Update footnote indexes on a built table +#' Update footnote indices on a built table +#' +#' Re-indexes footnotes within a built table. #' -#' Re-indexes footnotes within a built table #' @inheritParams gen_args #' -#' @details After adding or removing referential footnotes manually, -#' or after subsetting a table, the reference indexes (i.e. the -#' number associated with specific footnotes) may be incorrect. -#' This function recalculates these based on the full table. +#' @details +#' After adding or removing referential footnotes manually, or after subsetting a table, the reference indexes +#' (i.e. the number associated with specific footnotes) may be incorrect. This function recalculates these based +#' on the full table. +#' +#' @note In the future this should not generally need to be called manually. #' -#' @note In the future this should not generally need to be called -#' manually. #' @export update_ref_indexing <- function(tt) { col_fnotes <- c(list(row_fnotes = list()), col_footnotes(tt)) @@ -115,7 +113,6 @@ update_ref_indexing <- function(tt) { return(tt) } - rdf <- make_row_df(tt) rdf <- rdf[rdf$nreflines > 0, ] diff --git a/R/make_split_fun.R b/R/make_split_fun.R index 9080c6bf9..e1d97384d 100644 --- a/R/make_split_fun.R +++ b/R/make_split_fun.R @@ -1,28 +1,30 @@ -#' Variable Associated With a Split -#' -#' This function is intended for use when writing custom splitting -#' logic. In cases where the split is associated with a single -#' variable, the name of that variable will be returned. At time of -#' writing this includes splits generated via the -#' \code{\link{split_rows_by}}, \code{\link{split_cols_by}}, -#' \code{\link{split_rows_by_cuts}}, \code{\link{split_cols_by_cuts}}, -#' \code{\link{split_rows_by_cutfun}}, and -#' \code{\link{split_cols_by_cutfun}} layout directives. -#' @param spl Split. The split object -#' -#' @return for splits with a single variable associated with them, the split, for others, an error is raised. +#' Variable associated with a split +#' +#' This function is intended for use when writing custom splitting logic. In cases where the split is associated with +#' a single variable, the name of that variable will be returned. At time of writing this includes splits generated +#' via the [split_rows_by()], [split_cols_by()], [split_rows_by_cuts()], [split_cols_by_cuts()], +#' [split_rows_by_cutfun()], and [split_cols_by_cutfun()] layout directives. +#' +#' @param spl (`VarLevelSplit`)\cr the split object. +#' +#' @return For splits with a single variable associated with them, returns the split. Otherwise, an error is raised. +#' #' @export #' @seealso \code{\link{make_split_fun}} setGeneric("spl_variable", function(spl) standardGeneric("spl_variable")) + #' @rdname spl_variable #' @export setMethod("spl_variable", "VarLevelSplit", function(spl) spl_payload(spl)) + #' @rdname spl_variable #' @export setMethod("spl_variable", "VarDynCutSplit", function(spl) spl_payload(spl)) + #' @rdname spl_variable #' @export setMethod("spl_variable", "VarStaticCutSplit", function(spl) spl_payload(spl)) + #' @rdname spl_variable #' @export setMethod( @@ -37,7 +39,6 @@ in_col_split <- function(spl_ctx) { ) } - assert_splres_element <- function(pinfo, nm, len = NULL, component = NULL) { msg_2_append <- "" if (!is.null(component)) { @@ -72,28 +73,21 @@ validate_split_result <- function(pinfo, component = NULL) { #' Construct split result object #' -#' These functions can be used to create or add to a split result in -#' functions which implement core splitting or post-processing within -#' a custom split function. +#' These functions can be used to create or add to a split result in functions which implement core splitting or +#' post-processing within a custom split function. #' -#' @param values character or `list(SplitValue)`. The values associated -#' with each facet -#' @param datasplit `list(data.frame)`. The facet data for each facet -#' generated in the split -#' @param labels character. The labels associated with each facet -#' @param extras NULL or list. Extra values associated with each of -#' the facets which will be passed to analysis functions applied -#' within the facet. +#' @param values (`character` or `list(SplitValue)`)\cr the values associated with each facet. +#' @param datasplit (`list(data.frame)`)\cr the facet data for each facet generated in the split. +#' @param labels (`character`)\cr the labels associated with each facet. +#' @param extras (`list` or `NULL`)\cr extra values associated with each of the facets which will be passed to +#' analysis functions applied within the facet. #' -#' @return a named list representing the facets generated by the split -#' with elements `values`, `datasplit`, and `labels`, which are -#' the same length and correspond to each other elementwise. +#' @return A named list representing the facets generated by the split with elements `values`, `datasplit`, and +#' `labels`, which are the same length and correspond to each other element-wise. #' #' @details -#' These functions does various housekeeping to ensure that the split result -#' list is as the rtables internals expect it, most of which are not -#' relevant to end users. -#' +#' These functions performs various housekeeping tasks to ensure that the split result list is as the rtables +#' internals expect it, most of which are not relevant to end users. #' #' @examples #' splres <- make_split_result( @@ -107,9 +101,10 @@ validate_split_result <- function(pinfo, component = NULL) { #' datasplit = list(med = mtcars[1:20, ]), #' labels = "kinda some data" #' ) +#' +#' @family make_custom_split #' @rdname make_split_result #' @export -#' @family make_custom_split make_split_result <- function(values, datasplit, labels, extras = NULL) { if (length(values) == 1 && is(datasplit, "data.frame")) { datasplit <- list(datasplit) @@ -121,8 +116,9 @@ make_split_result <- function(values, datasplit, labels, extras = NULL) { .fixupvals(ret) } +#' @param splres (`list`)\cr a list representing the result of splitting. +#' #' @rdname make_split_result -#' @param splres list. A list representing the result of splitting. #' @export add_to_split_result <- function(splres, values, datasplit, labels, extras = NULL) { validate_split_result(splres) @@ -137,80 +133,61 @@ add_to_split_result <- function(splres, values, datasplit, labels, extras = NULL .can_take_spl_context <- function(f) any(c(".spl_context", "...") %in% names(formals(f))) -#' Create a Custom Splitting Function -#' -#' @param pre list. Zero or more functions which operate on the -#' incoming data and return a new data frame that should split via -#' `core_split`. They will be called on the data in the order they -#' appear in the list. -#' @param core_split function or NULL. If not NULL, a function which -#' accepts the same arguments do_base_split does, and returns the -#' same type of named list. Custom functions which override this -#' behavior cannot be used in column splits. -#' @param post list. Zero or more functions which should be called on -#' the list output by splitting. +#' Create a custom splitting function +#' +#' @param pre (`list`)\cr zero or more functions which operate on the incoming data and return a new data frame that +#' should split via `core_split`. They will be called on the data in the order they appear in the list. +#' @param core_split (`function` or `NULL`)\cr if non-`NULL`, a function which accepts the same arguments that +#' `do_base_split` does, and returns the same type of named list. Custom functions which override this behavior +#' cannot be used in column splits. +#' @param post (`list`)\cr zero or more functions which should be called on the list output by splitting. #' #' @details +#' Custom split functions can be thought of as (up to) 3 different types of manipulations of the splitting process: +#' +#' 1. Pre-processing of the incoming data to be split. +#' 2. (Row-splitting only) Customization of the core mapping of incoming data to facets. +#' 3. Post-processing operations on the set of facets (groups) generated by the split. +#' +#' This function provides an interface to create custom split functions by implementing and specifying sets of +#' operations in each of those classes of customization independently. +#' +#' Pre-processing functions (1), must accept: `df`, `spl`, `vals`, and `labels`, and can optionally accept +#' `.spl_context`. They then manipulate `df` (the incoming data for the split) and return a modified data frame. +#' This modified data frame *must* contain all columns present in the incoming data frame, but can add columns if +#' necessary (though we note that these new columns cannot be used in the layout as split or analysis variables, +#' because they will not be present when validity checking is done). +#' +#' The preprocessing component is useful for things such as manipulating factor levels, e.g., to trim unobserved ones +#' or to reorder levels based on observed counts, etc. +#' +#' Customization of core splitting (2) is currently only supported in row splits. Core splitting functions override the +#' fundamental splitting procedure, and are only necessary in rare cases. These must accept `spl`, `df`, `vals`, and +#' `labels`, and can optionally accept `.spl_context`. They must return a named list with elements, all of the same +#' length, as follows: +#' +#' - `datasplit`, containing a list of `data.frame` objects. +#' - `values`, containing values associated with the facets, which must be `character` or `SplitValue` objects. +#' These values will appear in the paths of the resulting table. +#' - `labels`, containing the character labels associated with `values` +#' +#' Post-processing functions (3) must accept the result of the core split as their first argument (which can be +#' anything), in addition to `spl`, and `fulldf`, and can optionally accept `.spl_context`. They must each return a +#' modified version of the same structure specified above for core splitting. +#' +#' In both the pre- and post-processing cases, multiple functions can be specified. When this happens, they are applied +#' sequentially, in the order they appear in the list passed to the relevant argument (`pre` and `post`, respectively). +#' +#' @return A custom function that can be used as a split function. +#' +#' @seealso [custom_split_funs] for a more detailed discussion on what custom split functions do. #' -#' Custom split functions can be thought of as (up to) 3 different -#' types of manipulations of the splitting process -#' -#' 1. Preprocessing of the incoming data to be split -#' 2. (Row-splitting only) Customization of the core mapping of incoming data to facets, and -#' 3. Postprocessing operations on the set of facets (groups) generated by the split. -#' -#' This function provides an interface to create custom split -#' functions by implementing and specifying sets of operations in each -#' of those classes of customization independently. -#' -#' Preprocessing functions (1), must accept: `df`, `spl`, `vals`, -#' `labels`, and can optionally accept `.spl_context`. They then -#' manipulate `df` (the incoming data for the split) and return a -#' modified data.frame. This modified data.frame *must* contain all -#' columns present in the incoming data.frame, but can add columns if -#' necessary (though we note that these new columns cannot be used in -#' the layout as split or analysis variables, because they will not be -#' present when validity checking is done). -#' -#' The preprocessing component is useful for things such as -#' manipulating factor levels, e.g., to trim unobserved ones or to -#' reorder levels based on observed counts, etc. -#' -#' Customization of core splitting (2) is currently only supported in -#' row splits. Core splitting functions override the fundamental -#' splitting procedure, and are only necessary in rare cases. These -#' must accept `spl`, `df`, `vals`, `labels`, and can optionally -#' accept `.spl_context`. They must return a named list with elements, -#' all of the same length, as follows: - `datasplit` (containing a -#' list of data.frames), - `values` containing values associated with -#' the facets, which must be `character` or `SplitValue` -#' objects. These values will appear in the paths of the resulting -#' table. - `labels` containing the character labels associated with -#' `values` -#' -#' Postprocessing functions (3) must accept the result of the core -#' split as their first argument (which as of writing can be -#' anything), in addition to `spl`, and `fulldf`, and can optionally -#' accept `.spl_context`. They must each return a modified version of -#' the same structure specified above for core splitting. -#' -#' In both the pre- and post-processing cases, multiple functions can -#' be specified. When this happens, they are applied sequentially, in -#' the order they appear in the list passed to the relevant argument -#' (`pre` and `post`, respectively). -#' -#' @return A function for use as a custom split function. -#' @export -#' @family make_custom_split -#' @seealso [custom_split_funs] for a more detailed discussion on what -#' custom split functions do. #' @examples #' mysplitfun <- make_split_fun( #' pre = list(drop_facet_levels), #' post = list(add_overall_facet("ALL", "All Arms")) #' ) #' -#' #' basic_table(show_colcounts = TRUE) %>% #' split_cols_by("ARM", split_fun = mysplitfun) %>% #' analyze("AGE") %>% @@ -264,6 +241,9 @@ add_to_split_result <- function(splres, values, datasplit, labels, extras = NULL #' analyze("AGE") #' silly_table <- build_table(lyt_silly, DM) #' silly_table +#' +#' @family make_custom_split +#' @export make_split_fun <- function(pre = list(), core_split = NULL, post = list()) { function(df, spl, @@ -317,25 +297,23 @@ make_split_fun <- function(pre = list(), core_split = NULL, post = list()) { } } -#' Add a combination facet in postprocessing +#' Add a combination facet in post-processing #' -#' @description Add a combination facet during postprocessing stage in a custom split fun. +#' Add a combination facet during the post-processing stage in a custom split fun. #' -#' @param name character(1). Name for the resulting facet (for use in pathing, etc). -#' @param label character(1). Label for the resulting facet. -#' @param levels character. Vector of levels to combine within the resulting facet. -#' @param extra list. Extra arguments to be passed to analysis functions applied -#' within the resulting facet. +#' @param name (`string`)\cr name for the resulting facet (for use in pathing, etc.). +#' @param label (`string`)\cr label for the resulting facet. +#' @param levels (`character`)\cr vector of levels to combine within the resulting facet. +#' @param extra (`list`)\cr extra arguments to be passed to analysis functions applied within the resulting facet. #' -#' @details For `add_combo_facet`, the data associated with the resulting -#' facet will be the data associated with the facets for each level in -#' `levels`, `rbound` together. In particular, this means that if those levels -#' are overlapping, data that appears in both will be duplicated. +#' @details +#' For `add_combo_facet`, the data associated with the resulting facet will be the data associated with the facets for +#' each level in `levels`, row-bound together. In particular, this means that if those levels are overlapping, data +#' that appears in both will be duplicated. #' -#' @return a function which can be used within the `post` argument in -#' `make_split_fun`. +#' @return A function which can be used within the `post` argument in [make_split_fun()]. #' -#' @seealso \code{\link{make_split_fun}} +#' @seealso [make_split_fun()] #' #' @examples #' mysplfun <- make_split_fun(post = list( @@ -352,8 +330,8 @@ make_split_fun <- function(pre = list(), core_split = NULL, post = list()) { #' #' tbl <- build_table(lyt, DM) #' -#' @export #' @family make_custom_split +#' @export add_combo_facet <- function(name, label = name, levels, extra = list()) { function(ret, spl, .spl_context, fulldf) { val <- LevelComboSplitValue(val = name, extr = extra, combolevels = levels, label = label) @@ -373,15 +351,16 @@ add_overall_facet <- function(name, label, extra = list()) { ) } -#' Trim Levels of Another Variable From Each Facet (Postprocessing split step) -#' @param innervar character. The variable(s) to trim (remove -#' unobserved levels) independently within each facet. +#' Trim levels of another variable from each facet (post-processing split step) +#' +#' @param innervar (`character`)\cr the variable(s) to trim (remove unobserved levels) independently within each facet. +#' +#' @return A function suitable for use in the `pre` (list) argument of `make_split_fun`. +#' +#' @seealso [make_split_fun()] #' -#' @return a function suitable for use in the `pre` -#' (list) argument of `make_split_fun` -#' @seealso make_split_fun -#' @export #' @family make_custom_split +#' @export trim_levels_in_facets <- function(innervar) { function(ret, ...) { for (var in innervar) { @@ -394,18 +373,19 @@ trim_levels_in_facets <- function(innervar) { } } -#' Preprocessing Functions for use in make_split_fun +#' Pre-processing function for use in `make_split_fun` #' -#' This function is intended for use as a preprocessing -#' component in `make_split_fun`, and should not be called +#' This function is intended for use as a pre-processing component in `make_split_fun`, and should not be called #' directly by end users. #' -#' @param df data.frame. The incoming data corresponding with the parent facet -#' @param spl Split. -#' @param ... dots. This is used internally to pass parameters. -#' @export -#' @seealso make_split_fun +#' @param df (`data.frame`)\cr the incoming data corresponding with the parent facet. +#' @param spl (`VarLevelSplit`)\cr the split. +#' @param ... additional parameters passed internally. +#' +#' @seealso [make_split_fun()] +#' #' @family make_custom_split +#' @export drop_facet_levels <- function(df, spl, ...) { if (!is(spl, "VarLevelSplit") || is.na(spl_payload(spl))) { stop("Unable to determine faceting variable in drop_facet_levels application.") diff --git a/R/make_subset_expr.R b/R/make_subset_expr.R index 001c75c48..71bd2cc46 100644 --- a/R/make_subset_expr.R +++ b/R/make_subset_expr.R @@ -3,6 +3,7 @@ ## we (sometimes) run into ## factor()[TRUE] giving (i.e. length 1) setGeneric("make_subset_expr", function(spl, val) standardGeneric("make_subset_expr")) + setMethod( "make_subset_expr", "VarLevelSplit", function(spl, val) { @@ -49,7 +50,6 @@ setMethod( } ) - ## XXX these are going to be ridiculously slow ## FIXME @@ -96,7 +96,6 @@ setMethod( } ) - ## I think this one is unnecessary, ## build_table collapses DynCutSplits into ## static ones. @@ -117,8 +116,6 @@ setMethod( function(spl, val) expression(TRUE) ) - - ## probably don't need this setMethod( @@ -146,7 +143,6 @@ setMethod( as.expression(bquote((.(a)) & .(b), list(a = ex1[[1]], b = ex2[[1]]))) } - make_pos_subset <- function(spls = pos_splits(pos), svals = pos_splvals(pos), pos) { @@ -158,7 +154,6 @@ make_pos_subset <- function(spls = pos_splits(pos), expr } - get_pos_extra <- function(svals = pos_splvals(pos), pos) { ret <- list() @@ -200,8 +195,6 @@ setMethod( } ) - - create_colinfo <- function(lyt, df, rtpos = TreePos(), counts = NULL, alt_counts_df = NULL, diff --git a/R/package.R b/R/package.R new file mode 100644 index 000000000..53c42924a --- /dev/null +++ b/R/package.R @@ -0,0 +1,9 @@ +#' @keywords internal +"_PACKAGE" + +#' @importFrom utils head head.matrix tail tail.matrix +#' @importFrom stats setNames na.omit prop.test binom.test relevel quantile +#' @importFrom htmltools tags tagList +#' @importFrom magrittr %>% +#' @import methods +NULL diff --git a/R/simple_analysis.R b/R/simple_analysis.R index e3044a360..e4e3754af 100644 --- a/R/simple_analysis.R +++ b/R/simple_analysis.R @@ -1,29 +1,30 @@ #' Default tabulation #' +#' This function is used when [analyze()] is invoked. #' -#' This function is used when \code{\link{analyze}} is invoked -#' -#' @param x the \emph{already split} data being tabulated for a particular cell/set of cells -#' @param \dots passed on directly +#' @param x (`vector`)\cr the *already split* data being tabulated for a particular cell/set of cells. +#' @param ... additional parameters to pass on. #' #' @details This function has the following behavior given particular types of inputs: -#' \describe{ -#' \item{numeric}{calls \code{\link{mean}} on \code{x}} -#' \item{logical}{calls \code{\link{sum}} on \code{x}} -#' \item{factor}{calls \code{\link{length}} on \code{x}} -#' } +#' \describe{ +#' \item{numeric}{calls [mean()] on `x`.} +#' \item{logical}{calls [sum()] on `x`.} +#' \item{factor}{calls [length()] on `x`.} +#' } #' -#' \code{in_rows} is called on the resulting value(s). +#' The [in_rows()] function is called on the resulting value(s). All other classes of input currently lead to an error. #' -#' All other classes of input currently lead to an error. -#' @export -#' @rdname rtinner -#' @author Gabriel Becker and Adrian Waddell #' @inherit in_rows return +#' +#' @author Gabriel Becker and Adrian Waddell +#' #' @examples #' simple_analysis(1:3) #' simple_analysis(iris$Species) #' simple_analysis(iris$Species == "setosa") +#' +#' @rdname rtinner +#' @export setGeneric("simple_analysis", function(x, ...) standardGeneric("simple_analysis")) #' @rdname rtinner diff --git a/R/split_funs.R b/R/split_funs.R index 5b98d83df..cc60197cf 100644 --- a/R/split_funs.R +++ b/R/split_funs.R @@ -8,8 +8,6 @@ ## .apply_spl_rawvals - Generate raw (i.e. non SplitValue object) partition values - - setGeneric( ".applysplit_rawvals", function(spl, df) standardGeneric(".applysplit_rawvals") @@ -40,59 +38,45 @@ setGeneric( function(spl, df, vals) standardGeneric(".applysplit_ref_vals") ) -#' @name custom_split_funs -#' @rdname custom_split_funs -#' @title Custom Split Functions +#' Custom split functions #' -#' @description Split functions provide the work-horse for `rtables`'s -#' generalized partitioning. These functions accept a (sub)set of incoming -#' data, a split object, and return 'splits' of that data. +#' Split functions provide the work-horse for `rtables`'s generalized partitioning. These functions accept a (sub)set +#' of incoming data and a split object, and return "splits" of that data. #' #' @section Custom Splitting Function Details: #' -#' User-defined custom split functions can perform any type of computation on -#' the incoming data provided that they meet the contract for generating -#' 'splits' of the incoming data 'based on' the split object. +#' User-defined custom split functions can perform any type of computation on the incoming data provided that they +#' meet the requirements for generating "splits" of the incoming data based on the split object. #' #' Split functions are functions that accept: -#' \describe{ -#' \item{df}{data.frame of incoming data to be split} -#' \item{spl}{a Split object. this is largely an internal detail custom -#' functions will not need to worry about, but \code{obj_name(spl)}, for -#' example, will give the name of the split as it will appear in paths in the -#' resulting table} -#' \item{vals}{Any pre-calculated values. If given non-null values, the values -#' returned should match these. Should be NULL in most cases and can likely be -#' ignored} -#' \item{labels}{Any pre-calculated value labels. Same as above for -#' \code{values}} -#' \item{trim}{If \code{TRUE}, resulting splits that are empty should be -#' removed} -#' \item{(Optional) .spl_context}{a data.frame describing previously performed -#' splits which collectively arrived at \code{df}} -#' } +#' \describe{ +#' \item{df}{a `data.frame` of incoming data to be split.} +#' \item{spl}{a Split object. This is largely an internal detail custom functions will not need to worry about, +#' but `obj_name(spl)`, for example, will give the name of the split as it will appear in paths in the resulting +#' table.} +#' \item{vals}{any pre-calculated values. If given non-`NULL` values, the values returned should match these. +#' Should be `NULL` in most cases and can usually be ignored.} +#' \item{labels}{any pre-calculated value labels. Same as above for `values`.} +#' \item{trim}{if `TRUE`, resulting splits that are empty are removed.} +#' \item{(optional) .spl_context}{a `data.frame` describing previously performed splits which collectively +#' arrived at `df`.} +#' } #' -#' The function must then output a \code{named list} with the following -#' elements: -#' -#' \describe{ -#' \item{values}{The vector of all values corresponding to the splits of -#' \code{df}} -#' \item{datasplit}{a list of data.frames representing the groupings of the -#' actual observations from \code{df}.} -#' \item{labels}{a character vector giving a string label for each value listed -#' in the \code{values} element above} -#' \item{(Optional) extras}{If present, extra arguments are to be passed to summary -#' and analysis functions whenever they are executed on the corresponding -#' element of \code{datasplit} or a subset thereof} -#' } +#' The function must then output a named `list` with the following elements: #' -#' One way to generate custom splitting functions is to wrap existing split -#' functions and modify either the incoming data before they are called or -#' their outputs. +#' \describe{ +#' \item{values}{the vector of all values corresponding to the splits of `df`.} +#' \item{datasplit}{a list of `data.frame`s representing the groupings of the actual observations from `df`.} +#' \item{labels}{a character vector giving a string label for each value listed in the `values` element above.} +#' \item{(optional) extras}{if present, extra arguments are to be passed to summary and analysis functions +#' whenever they are executed on the corresponding element of `datasplit` or a subset thereof.} +#' } +#' +#' One way to generate custom splitting functions is to wrap existing split functions and modify either the incoming +#' data before they are called or their outputs. #' -#' @seealso [make_split_fun()] for the API for creating custom split functions, -#' and [split_funcs] for a variety of pre-defined split functions. +#' @seealso [make_split_fun()] for the API for creating custom split functions, and [split_funcs] for a variety of +#' pre-defined split functions. #' #' @examples #' # Example of a picky split function. The number of values in the column variable @@ -133,9 +117,9 @@ setGeneric( #' tbl <- build_table(lyt, d1) #' tbl #' +#' @name custom_split_funs NULL - ## do various cleaning, and naming, plus ## ensure partinfo$values contains SplitValue objects only .fixupvals <- function(partinfo) { @@ -203,7 +187,6 @@ NULL partinfo$datasplit <- dpart } - partinfo$labels <- labels stopifnot(length(unique(sapply(partinfo, NROW))) == 1) @@ -239,24 +222,20 @@ NULL partinfo } -#' Apply Basic Split (For Use In Custom Split Functions) +#' Apply basic split (for use in custom split functions) #' -#' This function is intended for use inside custom split functions. It applies -#' the current split \emph{as if it had no custom splitting function} so that -#' those default splits can be further manipulated. +#' This function is intended for use inside custom split functions. It applies the current split *as if it had no +#' custom splitting function* so that those default splits can be further manipulated. #' #' @inheritParams gen_args -#' @param vals ANY. Already calculated/known values of the split. Generally -#' should be left as \code{NULL}. -#' @param labels character. Labels associated with \code{vals}. Should be -#' \code{NULL} when \code{vals} is, which should almost always be the case. -#' @param trim logical(1). Should groups corresponding to empty data subsets be -#' removed. Defaults to \code{FALSE}. +#' @param vals (`ANY`)\cr already calculated/known values of the split. Generally should be left as `NULL`. +#' @param labels (`character`)\cr labels associated with `vals`. Should be `NULL` whenever `vals` is, which should +#' almost always be the case. +#' @param trim (`flag`)\cr whether groups corresponding to empty data subsets should be removed. Defaults to +#' `FALSE`. #' -#' @return the result of the split being applied as if it had no custom split -#' function, see \code{\link{custom_split_funs}} +#' @return The result of the split being applied as if it had no custom split function. See [custom_split_funs]. #' -#' @export #' @examples #' uneven_splfun <- function(df, spl, vals = NULL, labels = NULL, trim = FALSE) { #' ret <- do_base_split(spl, df, vals, labels, trim) @@ -280,6 +259,8 @@ NULL #' #' tbl <- build_table(lyt, subset(ex_adae, as.numeric(ARM) <= 2)) #' tbl +#' +#' @export do_base_split <- function(spl, df, vals = NULL, labels = NULL, trim = FALSE) { spl2 <- spl split_fun(spl2) <- NULL @@ -289,7 +270,6 @@ do_base_split <- function(spl, df, vals = NULL, labels = NULL, trim = FALSE) { ) } - ### NB This is called at EACH level of recursive splitting do_split <- function(spl, df, @@ -403,7 +383,6 @@ do_split <- function(spl, vord <- vord[!is.na(vord)] } - ## FIXME: should be an S4 object, not a list ret <- list( values = vals[vord], @@ -414,7 +393,6 @@ do_split <- function(spl, ret } - .checkvarsok <- function(spl, df) { vars <- spl_payload(spl) ## could be multiple vars in the future? @@ -439,8 +417,6 @@ do_split <- function(spl, ### do NOT make it check, e.g., if the ref_group level of ### a factor is present in the data, because it may not be. - - setMethod( "check_validsplit", "VarLevelSplit", function(spl, df) { @@ -448,7 +424,6 @@ setMethod( } ) - setMethod( "check_validsplit", "MultiVarSplit", function(spl, df) { @@ -474,9 +449,6 @@ setMethod( } ) - - - ## default does nothing, add methods as they become ## required setMethod( @@ -484,8 +456,6 @@ setMethod( function(spl, df) invisible(NULL) ) - - setMethod( ".applysplit_rawvals", "VarLevelSplit", function(spl, df) { @@ -516,7 +486,6 @@ setMethod( function(spl, df) spl@levels ) - ## setMethod(".applysplit_rawvals", "NULLSplit", ## function(spl, df) "") @@ -525,7 +494,6 @@ setMethod( function(spl, df) spl_payload(spl) ) - ## formfactor here is gross we're gonna have ot do this ## all again in tthe data split part :-/ setMethod( @@ -535,7 +503,6 @@ setMethod( } ) - setMethod( ".applysplit_datapart", "VarLevelSplit", function(spl, df, vals) { @@ -554,7 +521,6 @@ setMethod( } ) - setMethod( ".applysplit_datapart", "MultiVarSplit", function(spl, df, vals) { @@ -586,12 +552,9 @@ setMethod( function(spl, df, vals) rep(list(df), times = length(vals)) ) - - ## setMethod(".applysplit_datapart", "NULLSplit", ## function(spl, df, vals) list(df[FALSE,])) - setMethod( ".applysplit_datapart", "VarStaticCutSplit", function(spl, df, vals) { @@ -604,7 +567,6 @@ setMethod( } ) - setMethod( ".applysplit_datapart", "CumulativeCutSplit", function(spl, df, vals) { @@ -624,7 +586,6 @@ setMethod( ## XXX TODO *CutSplit Methods - setClass("NullSentinel", contains = "NULL") nullsentinel <- new("NullSentinel") noarg <- function() nullsentinel @@ -650,8 +611,6 @@ setMethod( } ) - - setMethod( ".applysplit_ref_vals", "Split", function(spl, df, vals) rep(list(NULL), length(vals)) @@ -716,7 +675,6 @@ setMethod( function(spl, df, vals, labels) value_labels(spl) ) - make_splvalue_vec <- function(vals, extrs = list(list()), labels = vals) { if (length(vals) == 0) { return(vals) @@ -737,27 +695,23 @@ make_splvalue_vec <- function(vals, extrs = list(list()), labels = vals) { ) } - #' Split functions #' +#' @inheritParams sf_args +#' @inheritParams gen_args +#' @param vals (`ANY`)\cr for internal use only. +#' @param labels (`character`)\cr labels to use for the remaining levels instead of the existing ones. +#' @param excl (`character`)\cr levels to be excluded (they will not be reflected in the resulting table structure +#' regardless of presence in the data). #' #' @inheritSection custom_split_funs Custom Splitting Function Details #' -#' @inheritParams sf_args -#' @inheritParams gen_args -#' @param vals ANY. For internal use only. -#' @param labels character. Labels to use for the remaining levels instead of -#' the existing ones. -#' @param excl character. Levels to be excluded (they will not be reflected in -#' the resulting table structure regardless of presence in the data). +#' @inherit add_overall_level return #' #' @name split_funcs -#' @inherit add_overall_level return NULL -#' @rdname split_funcs -#' @export -#' + #' @examples #' lyt <- basic_table() %>% #' split_cols_by("ARM") %>% @@ -772,6 +726,8 @@ NULL #' tbl <- build_table(lyt, DM) #' tbl #' +#' @rdname split_funcs +#' @export remove_split_levels <- function(excl) { stopifnot(is.character(excl)) function(df, spl, vals = NULL, labels = NULL, trim = FALSE) { @@ -790,11 +746,9 @@ remove_split_levels <- function(excl) { } } -#' @rdname split_funcs -#' @param only character. Levels to retain (all others will be dropped). -#' @param reorder logical(1). Should the order of \code{only} be used as the -#' order of the children of the split. defaults to \code{TRUE} -#' @export +#' @param only (`character`)\cr levels to retain (all others will be dropped). +#' @param reorder (`flag`)\cr whether the order of `only` should be used as the order of the children of the +#' split. Defaults to `TRUE`. #' #' @examples #' lyt <- basic_table() %>% @@ -806,6 +760,9 @@ remove_split_levels <- function(excl) { #' #' tbl <- build_table(lyt, DM) #' tbl +#' +#' @rdname split_funcs +#' @export keep_split_levels <- function(only, reorder = TRUE) { function(df, spl, vals = NULL, labels = NULL, trim = FALSE) { var <- spl_payload(spl) @@ -829,9 +786,6 @@ keep_split_levels <- function(only, reorder = TRUE) { } } -#' @rdname split_funcs -#' @export -#' #' @examples #' lyt <- basic_table() %>% #' split_cols_by("ARM") %>% @@ -840,6 +794,9 @@ keep_split_levels <- function(only, reorder = TRUE) { #' #' tbl <- build_table(lyt, DM) #' tbl +#' +#' @rdname split_funcs +#' @export drop_split_levels <- function(df, spl, vals = NULL, @@ -860,9 +817,6 @@ drop_split_levels <- function(df, ) } -#' @rdname split_funcs -#' @export -#' #' @examples #' lyt <- basic_table() %>% #' split_cols_by("ARM") %>% @@ -871,6 +825,9 @@ drop_split_levels <- function(df, #' #' tbl <- build_table(lyt, DM) #' tbl +#' +#' @rdname split_funcs +#' @export drop_and_remove_levels <- function(excl) { stopifnot(is.character(excl)) function(df, spl, vals = NULL, labels = NULL, trim = FALSE) { @@ -887,14 +844,13 @@ drop_and_remove_levels <- function(excl) { } } - +#' @param neworder (`character`)\cr new order of factor levels. +#' @param newlabels (`character`)\cr labels for (new order of) factor levels. +#' @param drlevels (`flag`)\cr whether levels in the data which do not appear in `neworder` should be dropped. +#' Defaults to `TRUE`. +#' #' @rdname split_funcs -#' @param neworder character. New order or factor levels. -#' @param newlabels character. Labels for (new order of) factor levels -#' @param drlevels logical(1). Should levels in the data which do not appear in -#' \code{neworder} be dropped. Defaults to \code{TRUE} #' @export -#' reorder_split_levels <- function(neworder, newlabels = neworder, drlevels = TRUE) { @@ -920,14 +876,12 @@ reorder_split_levels <- function(neworder, } } - +#' @param innervar (`string`)\cr variable whose factor levels should be trimmed (e.g. empty levels dropped) +#' *separately within each grouping defined at this point in the structure*. +#' @param drop_outlevs (`flag`)\cr whether empty levels in the variable being split on (i.e. the "outer" +#' variable, not `innervar`) should be dropped. Defaults to `TRUE`. +#' #' @rdname split_funcs -#' @param innervar character(1). Variable whose factor levels should be trimmed -#' (e.g., empty levels dropped) \emph{separately within each grouping defined -#' at this point in the structure} -#' @param drop_outlevs logical(1). Should empty levels in the variable being -#' split on (i.e. the 'outer' variable, not \code{innervar}) be dropped? -#' Defaults to \code{TRUE} #' @export trim_levels_in_group <- function(innervar, drop_outlevs = TRUE) { myfun <- function(df, spl, vals = NULL, labels = NULL, trim = FALSE) { @@ -994,19 +948,16 @@ trim_levels_in_group <- function(innervar, drop_outlevs = TRUE) { part } -#' Add an virtual 'overall' level to split +#' Add a virtual "overall" level to split #' #' @inheritParams lyt_args #' @inheritParams sf_args -#' @param valname character(1). 'Value' to be assigned to the implicit -#' all-observations split level. Defaults to \code{"Overall"} -#' @param first logical(1). Should the implicit level appear first (\code{TRUE}) -#' or last \code{FALSE}. Defaults to \code{TRUE}. +#' @param valname (`string`)\cr value to be assigned to the implicit all-observations split level. Defaults to +#' `"Overall"`. +#' @param first (`flag`)\cr whether the implicit level should appear first (`TRUE`) or last (`FALSE`). Defaults +#' to `TRUE`. #' -#' @return a closure suitable for use as a splitting function (\code{splfun}) -#' when creating a table layout -#' -#' @export +#' @return A closure suitable for use as a splitting function (`splfun`) when creating a table layout. #' #' @examples #' lyt <- basic_table() %>% @@ -1030,6 +981,7 @@ trim_levels_in_group <- function(innervar, drop_outlevs = TRUE) { #' tbl2 <- build_table(lyt2, DM) #' tbl2 #' +#' @export add_overall_level <- function(valname = "Overall", label = valname, extra_args = list(), @@ -1050,23 +1002,25 @@ add_overall_level <- function(valname = "Overall", setClass("AllLevelsSentinel", contains = "character") # nocov start -#' @export #' @rdname add_combo_levels +#' @export select_all_levels <- new("AllLevelsSentinel") # nocov end -#' Add Combination Levels to split +#' Add combination levels to split +#' #' @inheritParams sf_args +#' @param combosdf (`data.frame` or `tbl_df`)\cr a data frame with columns `valname`, `label`, `levelcombo`, and +#' `exargs`. `levelcombo` and `exargs` should be list columns. Passing the `select_all_levels` object as a value in +#' `comblevels` column indicates that an overall/all-observations level should be created. +#' @param keep_levels (`character` or `NULL`)\cr if non-`NULL`, the levels to retain across both combination and +#' individual levels. +#' #' @inherit add_overall_level return -#' @param combosdf `data.frame`/`tbl_df`. Columns `valname`, `label`, `levelcombo`, -#' `exargs`. Of which `levelcombo` and `exargs` are list columns. Passing the -#' \code{select_all_levels} object as a value in the \code{comblevels} column -#' indicates that an overall/all-observations level should be created. -#' @param keep_levels character or NULL. If non-NULL, the levels to retain -#' across both combination and individual levels. -#' @note Analysis or summary functions for which the order matters should never -#' be used within the tabulation framework. -#' @export +#' +#' @note +#' Analysis or summary functions for which the order matters should never be used within the tabulation framework. +#' #' @examples #' library(tibble) #' combodf <- tribble( @@ -1115,6 +1069,8 @@ select_all_levels <- new("AllLevelsSentinel") #' #' tbl3 <- build_table(lyt3, smallerDM) #' tbl3 +#' +#' @export add_combo_levels <- function(combosdf, trim = FALSE, first = FALSE, @@ -1162,34 +1118,32 @@ add_combo_levels <- function(combosdf, myfun } - -#' Trim Levels to map -#' -#' This split function constructor creates a split function which trims -#' levels of a variable to reflect restrictions on the possible -#' combinations of two or more variables which are split by -#' (along the same axis) within a layout. -#' -#' @details When splitting occurs, the map is subset to the values of all -#' previously performed splits. The levels of the variable being split are -#' then pruned to only those still present within this subset of the map -#' representing the current hierarchical splitting context. +#' Trim levels to map #' -#' Splitting is then performed via the \code{\link{keep_split_levels}} split -#' function. +#' This split function constructor creates a split function which trims levels of a variable to reflect restrictions +#' on the possible combinations of two or more variables which the data is split by (along the same axis) within a +#' layout. #' -#' Each resulting element of the partition is then further trimmed by pruning -#' values of any remaining variables specified in the map to those values -#' allowed under the combination of the previous and current split. #' @param map data.frame. A data.frame defining allowed combinations of #' variables. Any combination at the level of this split not present in the #' map will be removed from the data, both for the variable being split and #' those present in the data but not associated with this split or any parents #' of it. -#' @return a fun +#' +#' @details +#' When splitting occurs, the map is subset to the values of all previously performed splits. The levels of the +#' variable being split are then pruned to only those still present within this subset of the map representing the +#' current hierarchical splitting context. +#' +#' Splitting is then performed via the [keep_split_levels()] split function. +#' +#' Each resulting element of the partition is then further trimmed by pruning values of any remaining variables +#' specified in the map to those values allowed under the combination of the previous and current split. +#' +#' @return A function that can be used as a split function. #' #' @seealso [trim_levels_in_group()] -#' @export +#' #' @examples #' map <- data.frame( #' LBCAT = c("CHEMISTRY", "CHEMISTRY", "CHEMISTRY", "IMMUNOLOGY"), @@ -1203,6 +1157,8 @@ add_combo_levels <- function(combosdf, #' split_rows_by("PARAMCD", split_fun = trim_levels_to_map(map = map)) %>% #' analyze("ANRIND") #' tbl <- build_table(lyt, ex_adlb) +#' +#' @export trim_levels_to_map <- function(map = NULL) { if (is.null(map) || any(sapply(map, class) != "character")) { stop( diff --git a/R/summary.R b/R/summary.R index 7f4d5fcba..a6d45da51 100644 --- a/R/summary.R +++ b/R/summary.R @@ -1,10 +1,12 @@ # paths summary ---- -#' @rdname make_col_row_df +#' Get a list of table row/column paths +#' +#' @param x (`VTableTree`)\cr an `rtable` object. #' -#' @title Return List with Table Row/Col Paths +#' @return A list of paths to each row/column within `x`. #' -#' @param x an `rtable` object +#' @seealso [cell_values()], [`fnotes_at_path<-`], [row_paths_summary()], [col_paths_summary()] #' #' @examples #' lyt <- basic_table() %>% @@ -19,18 +21,13 @@ #' #' cell_values(tbl, c("AGE", "Mean"), c("ARM", "B: Placebo")) #' -#' @return a list of paths to each row/column within \code{x} -#' -#' @seealso [cell_values()], [`fnotes_at_path<-`], -#' [row_paths_summary()], [col_paths_summary()] -#' +#' @rdname make_col_row_df #' @export row_paths <- function(x) { stopifnot(is_rtable(x)) make_row_df(x, visible_only = TRUE)$path } - #' @rdname make_col_row_df #' @export col_paths <- function(x) { @@ -40,17 +37,14 @@ col_paths <- function(x) { make_col_df(x, visible_only = TRUE)$path } - -#' Print Row/Col Paths Summary +#' Print row/column paths summary #' -#' @param x an `rtable` object +#' @param x (`VTableTree`)\cr an `rtable` object. #' -#' @export -#' @return A data.frame summarizing the row- or column-structure of \code{x}. -#' @examples -#' library(dplyr) +#' @return A data frame summarizing the row- or column-structure of `x`. #' -#' ex_adsl_MF <- ex_adsl %>% filter(SEX %in% c("M", "F")) +#' @examples +#' ex_adsl_MF <- ex_adsl %>% dplyr::filter(SEX %in% c("M", "F")) #' #' lyt <- basic_table() %>% #' split_cols_by("ARM") %>% @@ -77,6 +71,8 @@ col_paths <- function(x) { #' rrow("r1", 1, 2, 1, 2), rrow("r2", 3, 4, 2, 1) #' ) #' col_paths_summary(tbl2) +#' +#' @export row_paths_summary <- function(x) { stopifnot(is_rtable(x)) @@ -105,7 +101,6 @@ row_paths_summary <- function(x) { invisible(pagdf[, c("label", "indent", "node_class", "path")]) } - #' @rdname row_paths_summary #' @export col_paths_summary <- function(x) { @@ -131,12 +126,9 @@ col_paths_summary <- function(x) { invisible(pagdf[, c("label", "path")]) } - # Rows ---- # . Summarize Rows ---- - - # summarize_row_df <- # function(name, # label, @@ -157,74 +149,11 @@ col_paths_summary <- function(x) { # ) # } -summarize_row_df_unclassed <- function(name, - label, - indent, - depth, - rowtype, - indent_mod, - level, - ## footnotes = list() - num_row_refs = 0L, - num_cell_refs = 0L) { - list( - name = name, - label = label, - indent = indent, - depth = level, - rowtype = rowtype, - indent_mod = indent_mod, - level = level, - num_row_refs = num_row_refs, - num_cell_refs = num_cell_refs - ) - ## footnotes = footnotes)##, - ## stringsAsFactors = FALSE) -} - -srow_df_names <- names(summarize_row_df_unclassed("hi", "hi", 0L, 0L, "hi", 0L, 0L)) - -summarize_row_df_empty <- NULL - -fast_rsummry_bind <- function(lst) { - if (length(lst) == 0) { - return(summarize_row_df_empty) - } else if (length(lst) == 1L) { - return(as.data.frame(lst[[1]])) - } else { - res <- lapply( - seq_along(srow_df_names), - function(i) { - do.call(c, lapply(lst, function(x) { - if (length(x) > 0) x[[i]] else x - })) - } - ) - names(res) <- srow_df_names - res <- as.data.frame(res) - } - res -} - - - -#' summarize_rows -#' -#' `summarize_rows` is deprecated in favor of `make_row_df`. -#' @param obj `VTableTree`. -#' @return A data.frame summarizing the rows in \code{obj}. -#' @export -summarize_rows <- function(obj) { - .Deprecated("make_row_df") - rows <- summarize_rows_inner(obj, 0, 0) - fast_rsummry_bind(rows) -} - -#' Summarize Rows +#' Summarize rows #' #' @inheritParams gen_args -#' @param depth numeric(1). Depth. -#' @param indent numeric(1). Indent. +#' @param depth (`numeric(1)`)\cr depth. +#' @param indent (`numeric(1)`)\cr indent. #' #' @examples #' library(dplyr) @@ -295,94 +224,16 @@ setMethod( ## df } ) -#' @rdname int_methods -setMethod( - "summarize_rows_inner", "ElementaryTable", - function(obj, depth = 0, indent = 0) { - indent <- max(0L, indent + indent_mod(obj)) - lr <- summarize_rows_inner(tt_labelrow(obj), depth, indent) - if (!is.null(lr)) { - ret <- list(lr) - indent <- indent + 1 - } else { - ret <- list() - } - - els <- lapply(tree_children(obj), summarize_rows_inner, - depth = depth + 1, - indent = indent - ) - - c(ret, els) - ## df <- do.call(rbind, c(list(lr), els)) - ## row.names(df) <- NULL - ## df - } -) -.num_cell_refs <- function(tr) { - sum(vapply( - cell_footnotes(tr), - function(cfn) length(cfn) > 0, - FALSE - )) -} - -#' @rdname int_methods -setMethod( - "summarize_rows_inner", "TableRow", - function(obj, depth = 0, indent = 0) { - indent <- max(0L, indent + indent_mod(obj)) - - summarize_row_df_unclassed( - name = obj_name(obj), - label = obj_label(obj), - indent = indent, - depth = depth, - rowtype = "TableRow", - indent_mod = indent_mod(obj), - level = tt_level(obj), - num_row_refs = length(row_footnotes(obj)), - num_cell_refs = .num_cell_refs(obj) - ) - } -) -#' @rdname int_methods -setMethod( - "summarize_rows_inner", "LabelRow", - function(obj, depth = 0, indent = 0) { - indent <- max(0L, indent + indent_mod(obj)) - - if (labelrow_visible(obj)) { - summarize_row_df_unclassed( - name = obj_name(obj), - label = obj_label(obj), - indent = indent, - depth = depth, - rowtype = "LabelRow", - indent_mod = indent_mod(obj), - level = tt_level(obj), - num_row_refs = length(row_footnotes(obj)), - num_cell_refs = 0 - ) - } else { - summarize_row_df_empty - } - } -) - - # Print Table Structure ---- -#' Summarize Table +#' Summarize table #' -#' @param x a table object -#' @param detail either `row` or `subtable` +#' @param x (`VTableTree`)\cr a table object. +#' @param detail (`string`)\cr either `row` or `subtable`. #' -#' @export +#' @return No return value. Called for the side-effect of printing a row- or subtable-structure summary of `x`. #' -#' @return currently no return value. Called for the side-effect of printing a -#' row- or subtable-structure summary of \code{x}. #' @examples #' library(dplyr) #' @@ -407,6 +258,8 @@ setMethod( #' table_structure(tbl) #' #' table_structure(tbl, detail = "row") +#' +#' @export table_structure <- function(x, detail = c("subtable", "row")) { detail <- match.arg(detail) @@ -417,13 +270,12 @@ table_structure <- function(x, detail = c("subtable", "row")) { ) } - -#' @rdname int_methods +#' @param obj (`VTableTree`)\cr a table object. +#' @param depth (`numeric(1)`)\cr depth in tree. +#' @param indent (`numeric(1)`)\cr indent. +#' @param print_indent (`numeric(1)`)\cr indent for printing. #' -#' @param obj a table object -#' @param depth depth in tree -#' @param indent indent -#' @param print_indent indent for print +#' @rdname int_methods setGeneric( "table_structure_inner", function(obj, @@ -434,7 +286,6 @@ setGeneric( } ) - scat <- function(..., indent = 0, newline = TRUE) { txt <- paste(..., collapse = "", sep = "") @@ -456,17 +307,18 @@ is_empty_ElementaryTable <- function(x) { length(tree_children(x)) == 0 && is_empty_labelrow(tt_labelrow(x)) } +#' @param object (`VTableTree`)\cr a table object. +#' #' @rdname int_methods -#' @param object a table object #' @export setGeneric("str", function(object, ...) { standardGeneric("str") }) +#' @param max.level (`numeric(1)`)\cr passed to `utils::str`. Defaults to 3 for the `VTableTree` method, unlike +#' the underlying default of `NA`. `NA` is *not* appropriate for `VTableTree` objects. +#' #' @rdname int_methods -#' @param max.level numeric(1). Passed to `utils::str`. Defaults to 3 for the -#' `VTableTree` method, unlike the underlying default of `NA`. `NA` is *not* -#' appropriate for `VTableTree` objects. #' @export setMethod( "str", "VTableTree", @@ -480,8 +332,8 @@ setMethod( } ) -#' @rdname int_methods #' @inheritParams table_structure_inner +#' @rdname int_methods setMethod( "table_structure_inner", "TableTree", function(obj, depth = 0, indent = 0, print_indent = 0) { @@ -534,7 +386,6 @@ setMethod( indent = print_indent ) - indent <- indent + indent_mod(obj) table_structure_inner( @@ -542,7 +393,6 @@ setMethod( indent, print_indent + 1 ) - if (length(tree_children(obj)) == 0) { scat("children: - ", indent = print_indent + 1) } else { diff --git a/R/tree_accessors.R b/R/tree_accessors.R index 91eaff247..8b447db58 100644 --- a/R/tree_accessors.R +++ b/R/tree_accessors.R @@ -1,20 +1,22 @@ ## XXX Do we want add.labrows here or no? ## we have to choose one and stick to it. +#' Internal generics and methods +#' +#' These are internal methods that are documented only to satisfy `R CMD check`. End users should pay no +#' attention to this documentation. +#' +#' @param x (`ANY`)\cr the object. +#' @param obj (`ANY`)\cr the object. +#' #' @name internal_methods -#' @title Internal Generics and Methods #' @rdname int_methods -#' @description These are internal methods that are documented only to satisfy -#' `R CMD check`. End users should pay no attention to this documentation. -#' @inheritParams gen_args -#' @inheritParams constr_args -#' @inheritParams lyt_args -#' @param x The object. -#' @param obj The object. +#' @aliases int_methods NULL +#' @return The number of rows (`nrow`), columns (`ncol`), or both (`dim`) of the object. +#' #' @rdname dimensions -#' @return the number of rows (`nrow`), columns (`ncol`) or both (`dim`) of the object. #' @exportMethod nrow setMethod( "nrow", "VTableTree", @@ -28,12 +30,9 @@ setMethod( function(x) 1L ) -#' Table Dimensions -#' @rdname dimensions -#' -#' @exportMethod ncol +#' Table dimensions #' -#' @param x `TableTree` or `ElementaryTable` object +#' @param x (`TableTree` or `ElementaryTable`)\cr a table object. #' #' @examples #' lyt <- basic_table() %>% @@ -49,6 +48,8 @@ setMethod( #' NROW(tbl) #' NCOL(tbl) #' +#' @rdname dimensions +#' @exportMethod ncol setMethod( "ncol", "VTableNodeInfo", function(x) { @@ -94,20 +95,24 @@ setMethod( function(x) c(nrow(x), ncol(x)) ) -#' Retrieve or set the direct children of a Tree-style object +#' Retrieve or set the direct children of a tree-style object +#' +#' @param x (`TableTree` or `ElementaryTable`)\cr an object with a tree structure. +#' @param value (`list`)\cr new list of children. +#' +#' @return A list of direct children of `x`. #' -#' @param x An object with a Tree structure -#' @param value New list of children. -#' @return List of direct children of \code{x} #' @export #' @rdname tree_children setGeneric("tree_children", function(x) standardGeneric("tree_children")) + #' @exportMethod tree_children #' @rdname int_methods setMethod( "tree_children", c(x = "VTree"), function(x) x@children ) + #' @exportMethod tree_children #' @rdname int_methods setMethod( @@ -128,6 +133,7 @@ setMethod( #' @export #' @rdname tree_children setGeneric("tree_children<-", function(x, value) standardGeneric("tree_children<-")) + #' @exportMethod tree_children<- #' @rdname int_methods setMethod( @@ -137,6 +143,7 @@ setMethod( x } ) + #' @exportMethod tree_children<- #' @rdname int_methods setMethod( @@ -147,23 +154,26 @@ setMethod( } ) - -#' Retrieve or set Content Table from a `TableTree` +#' Retrieve or set content table from a `TableTree` +#' +#' Returns the content table of `obj` if it is a `TableTree` object, or `NULL` otherwise. #' -#' Returns the content table of \code{obj} if it is a \code{TableTree} object, or \code{NULL} otherwise +#' @param obj (`TableTree`)\cr the table object. +#' +#' @return the `ElementaryTable` containing the (top level) *content rows* of `obj` (or `NULL` if `obj` is not +#' a formal table object). #' -#' @param obj `TableTree`. The `TableTree` -#' @return the \code{ElementaryTable} containing the (top level) \emph{content rows} of \code{obj} ( or \code{NULL} -#' if \code{obj} is not a formal table object). #' @export #' @rdname content_table setGeneric("content_table", function(obj) standardGeneric("content_table")) + #' @exportMethod content_table #' @rdname int_methods setMethod( "content_table", "TableTree", function(obj) obj@content ) + #' @exportMethod content_table #' @rdname int_methods setMethod( @@ -171,10 +181,12 @@ setMethod( function(obj) NULL ) +#' @param value (`ElementaryTable`)\cr the new content table for `obj`. +#' #' @export -#' @param value `ElementaryTable`. The new content table for \code{obj}. #' @rdname content_table setGeneric("content_table<-", function(obj, value) standardGeneric("content_table<-")) + #' @exportMethod "content_table<-" #' @rdname int_methods setMethod( @@ -185,8 +197,8 @@ setMethod( } ) +#' @param for_analyze (`flag`) whether split is an analyze split. #' @rdname int_methods -#' @param for_analyze logical(1). setGeneric("next_rpos", function(obj, nested = TRUE, for_analyze = FALSE) standardGeneric("next_rpos")) #' @rdname int_methods @@ -206,6 +218,7 @@ setMethod( is(last_rowsplit(obj), "AnalyzeMultiVars")) ## should this be CompoundSplit? # nolint } } + #' @rdname int_methods setMethod( "next_rpos", "PreDataRowLayout", @@ -218,17 +231,18 @@ setMethod( } ) - - #' @rdname int_methods setMethod("next_rpos", "ANY", function(obj, nested) 1L) + #' @rdname int_methods setGeneric("next_cpos", function(obj, nested = TRUE) standardGeneric("next_cpos")) + #' @rdname int_methods setMethod( "next_cpos", "PreDataTableLayouts", function(obj, nested) next_cpos(clayout(obj), nested) ) + #' @rdname int_methods setMethod( "next_cpos", "PreDataColLayout", @@ -240,16 +254,19 @@ setMethod( } } ) + #' @rdname int_methods setMethod("next_cpos", "ANY", function(obj, nested) 1L) #' @rdname int_methods setGeneric("last_rowsplit", function(obj) standardGeneric("last_rowsplit")) + #' @rdname int_methods setMethod( "last_rowsplit", "NULL", function(obj) NULL ) + #' @rdname int_methods setMethod( "last_rowsplit", "SplitVector", @@ -261,6 +278,7 @@ setMethod( } } ) + #' @rdname int_methods setMethod( "last_rowsplit", "PreDataRowLayout", @@ -272,26 +290,31 @@ setMethod( } } ) + #' @rdname int_methods setMethod( "last_rowsplit", "PreDataTableLayouts", function(obj) last_rowsplit(rlayout(obj)) ) - - +# rlayout ---- ## TODO maybe export these? + #' @rdname int_methods setGeneric("rlayout", function(obj) standardGeneric("rlayout")) + #' @rdname int_methods setMethod( "rlayout", "PreDataTableLayouts", function(obj) obj@row_layout ) + #' @rdname int_methods setMethod("rlayout", "ANY", function(obj) PreDataRowLayout()) + #' @rdname int_methods setGeneric("rlayout<-", function(object, value) standardGeneric("rlayout<-")) + #' @rdname int_methods setMethod( "rlayout<-", "PreDataTableLayouts", @@ -301,43 +324,48 @@ setMethod( } ) - - - #' @rdname int_methods setGeneric("tree_pos", function(obj) standardGeneric("tree_pos")) + ## setMethod("tree_pos", "VNodeInfo", ## function(obj) obj@pos_in_tree) + #' @rdname int_methods setMethod( "tree_pos", "VLayoutNode", function(obj) obj@pos_in_tree ) - #' @rdname int_methods setGeneric("pos_subset", function(obj) standardGeneric("pos_subset")) + #' @rdname int_methods setMethod( "pos_subset", "TreePos", function(obj) obj@subset ) + ## setMethod("pos_subset", "VNodeInfo", ## function(obj) pos_subset(tree_pos(obj))) + #' @rdname int_methods setMethod( "pos_subset", "VLayoutNode", function(obj) pos_subset(tree_pos(obj)) ) + #' @rdname int_methods setGeneric("pos_splits", function(obj) standardGeneric("pos_splits")) + #' @rdname int_methods setMethod( "pos_splits", "TreePos", function(obj) obj@splits ) + ## setMethod("pos_splits", "VNodeInfo", ## function(obj) pos_splits(tree_pos(obj))) + #' @rdname int_methods setMethod( "pos_splits", "VLayoutNode", @@ -346,6 +374,7 @@ setMethod( #' @rdname int_methods setGeneric("pos_splvals", function(obj) standardGeneric("pos_splvals")) + #' @rdname int_methods setMethod( "pos_splvals", "TreePos", @@ -354,15 +383,16 @@ setMethod( ## setMethod("pos_splvals", "VNodeInfo", ## function(obj) pos_splvals(tree_pos(obj))) + #' @rdname int_methods setMethod( "pos_splvals", "VLayoutNode", function(obj) pos_splvals(tree_pos(obj)) ) - #' @rdname int_methods setGeneric("pos_splval_labels", function(obj) standardGeneric("pos_splval_labels")) + #' @rdname int_methods setMethod( "pos_splval_labels", "TreePos", @@ -376,14 +406,15 @@ setMethod( ## setMethod("pos_splval_labels", "VLayoutNode", ## function(obj) pos_splval_labels(tree_pos(obj))) - #' @rdname int_methods setGeneric("spl_payload", function(obj) standardGeneric("spl_payload")) + #' @rdname int_methods setMethod("spl_payload", "Split", function(obj) obj@payload) #' @rdname int_methods setGeneric("spl_payload<-", function(obj, value) standardGeneric("spl_payload<-")) + #' @rdname int_methods setMethod("spl_payload<-", "Split", function(obj, value) { obj@payload <- value @@ -392,8 +423,10 @@ setMethod("spl_payload<-", "Split", function(obj, value) { #' @rdname int_methods setGeneric("spl_label_var", function(obj) standardGeneric("spl_label_var")) + #' @rdname int_methods setMethod("spl_label_var", "VarLevelSplit", function(obj) obj@value_label_var) + ## TODO revisit. do we want to do this? used in vars_in_layout, but only ## for convenience. #' @rdname int_methods @@ -404,12 +437,15 @@ setMethod("spl_label_var", "Split", function(obj) NULL) #' Methods for generics in the `formatters` package #' #' See the `formatters` documentation for descriptions of these generics. +#' #' @inheritParams gen_args #' -#' @return for getters, the current value of the component being accessed -#' on `obj`, for setters, a modified copy of `obj` with the new value. +#' @return +#' * Accessor functions return the current value of the component being accessed of `obj` +#' * Setter functions return a modified copy of `obj` with the new value. #' #' @rdname formatters_methods +#' @aliases formatters_methods #' @exportMethod obj_name setMethod( "obj_name", "VNodeInfo", @@ -422,6 +458,7 @@ setMethod( "obj_name", "Split", function(obj) obj@name ) + #' @rdname formatters_methods #' @exportMethod obj_name<- setMethod( @@ -431,6 +468,7 @@ setMethod( obj } ) + #' @rdname formatters_methods #' @exportMethod obj_name<- setMethod( @@ -441,7 +479,6 @@ setMethod( } ) - ### Label related things #' @rdname formatters_methods #' @exportMethod obj_label @@ -450,6 +487,7 @@ setMethod("obj_label", "Split", function(obj) obj@split_label) #' @rdname formatters_methods #' @exportMethod obj_label setMethod("obj_label", "TableRow", function(obj) obj@label) + ## XXX Do we want a convenience for VTableTree that ## grabs the label from the LabelRow or will ## that just muddy the waters? @@ -494,7 +532,6 @@ setMethod( } ) - #' @rdname formatters_methods #' @exportMethod obj_label<- setMethod( @@ -515,6 +552,7 @@ setMethod( ### Label rows. #' @rdname int_methods setGeneric("tt_labelrow", function(obj) standardGeneric("tt_labelrow")) + #' @rdname int_methods setMethod( "tt_labelrow", "VTableTree", @@ -523,6 +561,7 @@ setMethod( #' @rdname int_methods setGeneric("tt_labelrow<-", function(obj, value) standardGeneric("tt_labelrow<-")) + #' @rdname int_methods setMethod( "tt_labelrow<-", c("VTableTree", "LabelRow"), @@ -537,6 +576,7 @@ setMethod( #' @rdname int_methods setGeneric("labelrow_visible", function(obj) standardGeneric("labelrow_visible")) + #' @rdname int_methods setMethod( "labelrow_visible", "VTableTree", @@ -550,6 +590,7 @@ setMethod( "labelrow_visible", "LabelRow", function(obj) obj@visible ) + #' @rdname int_methods setMethod( "labelrow_visible", "VAnalyzeSplit", @@ -558,6 +599,7 @@ setMethod( #' @rdname int_methods setGeneric("labelrow_visible<-", function(obj, value) standardGeneric("labelrow_visible<-")) + #' @rdname int_methods setMethod( "labelrow_visible<-", "VTableTree", @@ -587,21 +629,23 @@ setMethod( } ) - ## TRUE is always, FALSE is never, NA is only when no ## content function (or rows in an instantiated table) is present #' @rdname int_methods setGeneric("label_kids", function(spl) standardGeneric("label_kids")) + #' @rdname int_methods setMethod("label_kids", "Split", function(spl) spl@label_children) #' @rdname int_methods setGeneric("label_kids<-", function(spl, value) standardGeneric("label_kids<-")) + #' @rdname int_methods setMethod("label_kids<-", c("Split", "character"), function(spl, value) { label_kids(spl) <- .labelkids_helper(value) spl }) + #' @rdname int_methods setMethod("label_kids<-", c("Split", "logical"), function(spl, value) { spl@label_children <- value @@ -610,6 +654,7 @@ setMethod("label_kids<-", c("Split", "logical"), function(spl, value) { #' @rdname int_methods setGeneric("vis_label", function(spl) standardGeneric("vis_label")) + #' @rdname int_methods setMethod("vis_label", "Split", function(spl) { .labelkids_helper(label_position(spl)) @@ -626,19 +671,18 @@ setMethod("vis_label", "Split", function(spl) { ## spl ## }) - - #' @rdname int_methods setGeneric("label_position", function(spl) standardGeneric("label_position")) + #' @rdname int_methods setMethod("label_position", "Split", function(spl) spl@split_label_position) #' @rdname int_methods setMethod("label_position", "VAnalyzeSplit", function(spl) spl@var_label_position) ## split_label_position) - #' @rdname int_methods setGeneric("label_position<-", function(spl, value) standardGeneric("label_position<-")) + #' @rdname int_methods setMethod("label_position<-", "Split", function(spl, value) { value <- match.arg(value, valid_lbl_pos) @@ -646,20 +690,17 @@ setMethod("label_position<-", "Split", function(spl, value) { spl }) +### Function accessors (summary, tabulation and split) ---- - - - - - -### Function acessors (summary, tabulation and split) #' @rdname int_methods setGeneric("content_fun", function(obj) standardGeneric("content_fun")) + #' @rdname int_methods setMethod("content_fun", "Split", function(obj) obj@content_fun) #' @rdname int_methods setGeneric("content_fun<-", function(object, value) standardGeneric("content_fun<-")) + #' @rdname int_methods setMethod("content_fun<-", "Split", function(object, value) { object@content_fun <- value @@ -668,12 +709,13 @@ setMethod("content_fun<-", "Split", function(object, value) { #' @rdname int_methods setGeneric("analysis_fun", function(obj) standardGeneric("analysis_fun")) + #' @rdname int_methods setMethod("analysis_fun", "AnalyzeVarSplit", function(obj) obj@analysis_fun) + #' @rdname int_methods setMethod("analysis_fun", "AnalyzeColVarSplit", function(obj) obj@analysis_fun) - ## not used and probably not needed ## #' @rdname int_methods ## setGeneric("analysis_fun<-", function(object, value) standardGeneric("analysis_fun<-")) @@ -691,11 +733,9 @@ setMethod("analysis_fun", "AnalyzeColVarSplit", function(obj) obj@analysis_fun) ## object ## }) - - - #' @rdname int_methods setGeneric("split_fun", function(obj) standardGeneric("split_fun")) + #' @rdname int_methods setMethod("split_fun", "CustomizableSplit", function(obj) obj@split_fun) @@ -707,6 +747,7 @@ setMethod("split_fun", "Split", function(obj) NULL) #' @rdname int_methods setGeneric("split_fun<-", function(obj, value) standardGeneric("split_fun<-")) + #' @rdname int_methods setMethod("split_fun<-", "CustomizableSplit", function(obj, value) { obj@split_fun <- value @@ -729,41 +770,43 @@ setMethod( ) # nocov end -## Content specification related accessors +## Content specification related accessors ---- + #' @rdname int_methods setGeneric("content_extra_args", function(obj) standardGeneric("content_extra_args")) + #' @rdname int_methods setMethod("content_extra_args", "Split", function(obj) obj@content_extra_args) #' @rdname int_methods setGeneric("content_extra_args<-", function(object, value) standardGeneric("content_extra_args<-")) + #' @rdname int_methods setMethod("content_extra_args<-", "Split", function(object, value) { object@content_extra_args <- value object }) - #' @rdname int_methods setGeneric("content_var", function(obj) standardGeneric("content_var")) + #' @rdname int_methods setMethod("content_var", "Split", function(obj) obj@content_var) #' @rdname int_methods setGeneric("content_var<-", function(object, value) standardGeneric("content_var<-")) + #' @rdname int_methods setMethod("content_var<-", "Split", function(object, value) { object@content_var <- value object }) +### Miscellaneous accessors ---- - - - -### Miscelaneous accessors #' @rdname int_methods setGeneric("avar_inclNAs", function(obj) standardGeneric("avar_inclNAs")) + #' @rdname int_methods setMethod( "avar_inclNAs", "VAnalyzeSplit", @@ -772,6 +815,7 @@ setMethod( #' @rdname int_methods setGeneric("avar_inclNAs<-", function(obj, value) standardGeneric("avar_inclNAs<-")) + #' @rdname int_methods setMethod( "avar_inclNAs<-", "VAnalyzeSplit", @@ -782,11 +826,13 @@ setMethod( #' @rdname int_methods setGeneric("spl_labelvar", function(obj) standardGeneric("spl_labelvar")) + #' @rdname int_methods setMethod("spl_labelvar", "VarLevelSplit", function(obj) obj@value_label_var) #' @rdname int_methods setGeneric("spl_child_order", function(obj) standardGeneric("spl_child_order")) + #' @rdname int_methods setMethod("spl_child_order", "VarLevelSplit", function(obj) obj@value_order) @@ -795,6 +841,7 @@ setGeneric( "spl_child_order<-", function(obj, value) standardGeneric("spl_child_order<-") ) + #' @rdname int_methods setMethod( "spl_child_order<-", "VarLevelSplit", @@ -810,18 +857,21 @@ setMethod( "ManualSplit", function(obj) obj@levels ) + #' @rdname int_methods setMethod( "spl_child_order", "MultiVarSplit", function(obj) spl_varnames(obj) ) + #' @rdname int_methods setMethod( "spl_child_order", "AllSplit", function(obj) character() ) + #' @rdname int_methods setMethod( "spl_child_order", @@ -831,6 +881,7 @@ setMethod( #' @rdname int_methods setGeneric("root_spl", function(obj) standardGeneric("root_spl")) + #' @rdname int_methods setMethod( "root_spl", "PreDataAxisLayout", @@ -839,6 +890,7 @@ setMethod( #' @rdname int_methods setGeneric("root_spl<-", function(obj, value) standardGeneric("root_spl<-")) + #' @rdname int_methods setMethod( "root_spl<-", "PreDataAxisLayout", @@ -849,12 +901,15 @@ setMethod( ) #' Row attribute accessors +#' #' @inheritParams gen_args -#' @return various, depending on the accessor called. -#' @rdname row_accessors -#' @export #' +#' @return Various return values depending on the accessor called. +#' +#' @export +#' @rdname row_accessors setGeneric("obj_avar", function(obj) standardGeneric("obj_avar")) + #' @rdname row_accessors #' @exportMethod obj_avar setMethod("obj_avar", "TableRow", function(obj) obj@var_analyzed) @@ -866,12 +921,14 @@ setMethod("obj_avar", "ElementaryTable", function(obj) obj@var_analyzed) #' @export #' @rdname row_accessors setGeneric("row_cells", function(obj) standardGeneric("row_cells")) + #' @rdname row_accessors #' @exportMethod row_cells setMethod("row_cells", "TableRow", function(obj) obj@leaf_value) #' @rdname row_accessors setGeneric("row_cells<-", function(obj, value) standardGeneric("row_cells<-")) + #' @rdname row_accessors #' @exportMethod row_cells setMethod("row_cells<-", "TableRow", function(obj, value) { @@ -882,6 +939,7 @@ setMethod("row_cells<-", "TableRow", function(obj, value) { #' @export #' @rdname row_accessors setGeneric("row_values", function(obj) standardGeneric("row_values")) + #' @rdname row_accessors #' @exportMethod row_values setMethod("row_values", "TableRow", function(obj) rawvalues(obj@leaf_value)) @@ -890,6 +948,7 @@ setMethod("row_values", "TableRow", function(obj) rawvalues(obj@leaf_value)) #' @rdname row_accessors #' @exportMethod row_values<- setGeneric("row_values<-", function(obj, value) standardGeneric("row_values<-")) + #' @rdname row_accessors #' @exportMethod row_values<- setMethod( @@ -899,6 +958,7 @@ setMethod( obj } ) + #' @rdname row_accessors #' @exportMethod row_values<- setMethod( @@ -910,6 +970,7 @@ setMethod( #' @rdname int_methods setGeneric("spanned_values", function(obj) standardGeneric("spanned_values")) + #' @rdname int_methods setMethod( "spanned_values", "TableRow", @@ -928,6 +989,7 @@ setMethod( #' @rdname int_methods setGeneric("spanned_cells", function(obj) standardGeneric("spanned_cells")) + #' @rdname int_methods setMethod( "spanned_cells", "TableRow", @@ -942,6 +1004,7 @@ setMethod( ) } ) + #' @rdname int_methods setMethod( "spanned_cells", "LabelRow", @@ -952,6 +1015,7 @@ setMethod( #' @rdname int_methods setGeneric("spanned_values<-", function(obj, value) standardGeneric("spanned_values<-")) + #' @rdname int_methods setMethod( "spanned_values<-", "TableRow", @@ -989,6 +1053,7 @@ setMethod( obj } ) + #' @rdname int_methods setMethod( "spanned_values<-", "LabelRow", @@ -1000,17 +1065,17 @@ setMethod( } ) - - ### Format manipulation ### obj_format<- is not recursive ## TODO export these? #' @rdname formatters_methods #' @export setMethod("obj_format", "VTableNodeInfo", function(obj) obj@format) + #' @rdname formatters_methods #' @export setMethod("obj_format", "CellValue", function(obj) attr(obj, "format", exact = TRUE)) + #' @rdname formatters_methods #' @export setMethod("obj_format", "Split", function(obj) obj@split_format) @@ -1021,12 +1086,14 @@ setMethod("obj_format<-", "VTableNodeInfo", function(obj, value) { obj@format <- value obj }) + #' @rdname formatters_methods #' @export setMethod("obj_format<-", "Split", function(obj, value) { obj@split_format <- value obj }) + #' @rdname formatters_methods #' @export setMethod("obj_format<-", "CellValue", function(obj, value) { @@ -1055,13 +1122,10 @@ setMethod("obj_na_str<-", "Split", function(obj, value) { obj }) - #' @rdname int_methods #' @export setMethod("obj_na_str", "VTableNodeInfo", function(obj) obj@na_str) - - #' @rdname formatters_methods #' @export setMethod("obj_na_str", "Split", function(obj) obj@split_na_str) @@ -1078,8 +1142,9 @@ setGeneric("set_format_recursive", function(obj, format, na_str, override = FALS standardGeneric("set_format_recursive") }) +#' @param override (`flag`)\cr whether to override attribute. +#' #' @rdname int_methods -#' @param override logical(1). setMethod( "set_format_recursive", "TableRow", function(obj, format, na_str, override = FALSE) { @@ -1107,11 +1172,13 @@ setMethod( obj } ) + #' @rdname int_methods setMethod( "set_format_recursive", "LabelRow", function(obj, format, override = FALSE) obj ) + setMethod( "set_format_recursive", "VTableTree", function(obj, format, na_str, override = FALSE) { @@ -1142,41 +1209,43 @@ setMethod( #' @rdname int_methods setGeneric("content_format", function(obj) standardGeneric("content_format")) + #' @rdname int_methods setMethod("content_format", "Split", function(obj) obj@content_format) #' @rdname int_methods setGeneric("content_format<-", function(obj, value) standardGeneric("content_format<-")) + #' @rdname int_methods setMethod("content_format<-", "Split", function(obj, value) { obj@content_format <- value obj }) - #' @rdname int_methods setGeneric("content_na_str", function(obj) standardGeneric("content_na_str")) + #' @rdname int_methods setMethod("content_na_str", "Split", function(obj) obj@content_na_str) #' @rdname int_methods setGeneric("content_na_str<-", function(obj, value) standardGeneric("content_na_str<-")) + #' @rdname int_methods setMethod("content_na_str<-", "Split", function(obj, value) { obj@content_na_str <- value obj }) - -#' Value Formats +#' Value formats #' -#' Returns a matrix of formats for the cells in a table -#' @param obj A table or row object. -#' @param default `FormatSpec`. +#' Returns a matrix of formats for the cells in a table. #' -#' @return Matrix (storage mode list) containing the effective format for each -#' cell position in the table (including 'virtual' cells implied by label rows, -#' whose formats are always `NULL`). +#' @param obj (`VTableTree` or `TableRow`)\cr a table or row object. +#' @param default (`string`, `function`, or `list`)\cr default format. +#' +#' @return Matrix (storage mode list) containing the effective format for each cell position in the table +#' (including 'virtual' cells implied by label rows, whose formats are always `NULL`). #' #' @seealso [table_shell()] and [table_shell_str()] for information on the table format structure. #' @@ -1190,6 +1259,7 @@ setMethod("content_na_str<-", "Split", function(obj, value) { #' #' @export setGeneric("value_formats", function(obj, default = obj_format(obj)) standardGeneric("value_formats")) + #' @rdname value_formats setMethod( "value_formats", "ANY", @@ -1197,6 +1267,7 @@ setMethod( obj_format(obj) %||% default } ) + #' @rdname value_formats setMethod( "value_formats", "TableRow", @@ -1208,6 +1279,7 @@ setMethod( formats } ) + #' @rdname value_formats setMethod( "value_formats", "LabelRow", @@ -1215,6 +1287,7 @@ setMethod( rep(list(NULL), ncol(obj)) } ) + #' @rdname value_formats setMethod( "value_formats", "VTableTree", @@ -1230,7 +1303,6 @@ setMethod( } ) - ### Collect all leaves of a current tree ### This is a workhorse function in various ### places @@ -1238,12 +1310,14 @@ setMethod( ### be used on all tree-based structures in the ### framework. -#' Collect leaves of a table tree +#' Collect leaves of a `TableTree` +#' #' @inheritParams gen_args -#' @param incl.cont logical. Include rows from content tables within the tree. Defaults to \code{TRUE} -#' @param add.labrows logical. Include label rows. Defaults to \code{FALSE} -#' @return A list of \code{TableRow} objects for all rows in the table -#' @name collect_leaves +#' @param incl.cont (`flag`)\cr whether to include rows from content tables within the tree. Defaults to `TRUE`. +#' @param add.labrows (`flag`)\cr whether to include label rows. Defaults to `FALSE`. +#' +#' @return A list of `TableRow` objects for all rows in the table. +#' #' @export setGeneric("collect_leaves", function(tt, incl.cont = TRUE, add.labrows = FALSE) { @@ -1252,10 +1326,10 @@ setGeneric("collect_leaves", signature = "tt" ) -#' @rdname int_methods #' @inheritParams collect_leaves +#' +#' @rdname int_methods #' @exportMethod collect_leaves - setMethod( "collect_leaves", "TableTree", function(tt, incl.cont = TRUE, add.labrows = FALSE) { @@ -1277,7 +1351,6 @@ setMethod( #' @rdname int_methods #' @exportMethod collect_leaves - setMethod( "collect_leaves", "ElementaryTable", function(tt, incl.cont = TRUE, add.labrows = FALSE) { @@ -1291,7 +1364,6 @@ setMethod( #' @rdname int_methods #' @exportMethod collect_leaves - setMethod( "collect_leaves", "VTree", function(tt, incl.cont, add.labrows) { @@ -1321,7 +1393,6 @@ setMethod( } ) - #' @rdname int_methods #' @exportMethod collect_leaves setMethod( @@ -1334,11 +1405,15 @@ setMethod( n_leaves <- function(tt, ...) { length(collect_leaves(tt, ...)) } -### Spanning information + +### Spanning information ---- + #' @rdname int_methods setGeneric("row_cspans", function(obj) standardGeneric("row_cspans")) + #' @rdname int_methods setMethod("row_cspans", "TableRow", function(obj) obj@colspans) + #' @rdname int_methods setMethod( "row_cspans", "LabelRow", @@ -1347,20 +1422,22 @@ setMethod( #' @rdname int_methods setGeneric("row_cspans<-", function(obj, value) standardGeneric("row_cspans<-")) + #' @rdname int_methods setMethod("row_cspans<-", "TableRow", function(obj, value) { obj@colspans <- value obj }) + #' @rdname int_methods setMethod("row_cspans<-", "LabelRow", function(obj, value) { stop("attempted to set colspans for LabelRow") # nocov }) - ## XXX TODO colapse with above? #' @rdname int_methods setGeneric("cell_cspan", function(obj) standardGeneric("cell_cspan")) + #' @rdname int_methods setMethod( "cell_cspan", "CellValue", @@ -1372,6 +1449,7 @@ setGeneric( "cell_cspan<-", function(obj, value) standardGeneric("cell_cspan<-") ) + #' @rdname int_methods setMethod("cell_cspan<-", "CellValue", function(obj, value) { ## obj@colspan <- value @@ -1381,6 +1459,7 @@ setMethod("cell_cspan<-", "CellValue", function(obj, value) { #' @rdname int_methods setGeneric("cell_align", function(obj) standardGeneric("cell_align")) + #' @rdname int_methods setMethod( "cell_align", "CellValue", @@ -1392,6 +1471,7 @@ setGeneric( "cell_align<-", function(obj, value) standardGeneric("cell_align<-") ) + #' @rdname int_methods setMethod("cell_align<-", "CellValue", function(obj, value) { ## obj@colspan <- value @@ -1405,24 +1485,25 @@ setMethod("cell_align<-", "CellValue", function(obj, value) { obj }) +### Level (indent) in tree structure ---- - - -### Level (indent) in tree structure #' @rdname int_methods setGeneric("tt_level", function(obj) standardGeneric("tt_level")) + ## this will hit everything via inheritence #' @rdname int_methods setMethod("tt_level", "VNodeInfo", function(obj) obj@level) #' @rdname int_methods setGeneric("tt_level<-", function(obj, value) standardGeneric("tt_level<-")) + ## this will hit everyhing via inheritence #' @rdname int_methods setMethod("tt_level<-", "VNodeInfo", function(obj, value) { obj@level <- as.integer(value) obj }) + #' @rdname int_methods setMethod( "tt_level<-", "VTableTree", @@ -1439,21 +1520,25 @@ setMethod( #' @rdname int_methods #' @export setGeneric("indent_mod", function(obj) standardGeneric("indent_mod")) + #' @rdname int_methods setMethod( "indent_mod", "Split", function(obj) obj@indent_modifier ) + #' @rdname int_methods setMethod( "indent_mod", "VTableNodeInfo", function(obj) obj@indent_modifier ) + #' @rdname int_methods setMethod( "indent_mod", "ANY", function(obj) attr(obj, "indent_mod", exact = TRUE) %||% 0L ) + #' @rdname int_methods setMethod( "indent_mod", "RowsVerticalSection", @@ -1465,13 +1550,15 @@ setMethod( } ) -#' @rdname int_methods -#' @export #' @examples #' indent_mod(tbl) #' indent_mod(tbl) <- 1L #' tbl +#' +#' @rdname int_methods +#' @export setGeneric("indent_mod<-", function(obj, value) standardGeneric("indent_mod<-")) + #' @rdname int_methods setMethod( "indent_mod<-", "Split", @@ -1480,6 +1567,7 @@ setMethod( obj } ) + #' @rdname int_methods setMethod( "indent_mod<-", "VTableNodeInfo", @@ -1488,6 +1576,7 @@ setMethod( obj } ) + #' @rdname int_methods setMethod( "indent_mod<-", "CellValue", @@ -1496,6 +1585,7 @@ setMethod( obj } ) + #' @rdname int_methods setMethod( "indent_mod<-", "RowsVerticalSection", @@ -1514,18 +1604,18 @@ setMethod( } ) - - #' @rdname int_methods setGeneric( "content_indent_mod", function(obj) standardGeneric("content_indent_mod") ) + #' @rdname int_methods setMethod( "content_indent_mod", "Split", function(obj) obj@content_indent_modifier ) + #' @rdname int_methods setMethod( "content_indent_mod", "VTableNodeInfo", @@ -1537,6 +1627,7 @@ setGeneric( "content_indent_mod<-", function(obj, value) standardGeneric("content_indent_mod<-") ) + #' @rdname int_methods setMethod( "content_indent_mod<-", "Split", @@ -1545,6 +1636,7 @@ setMethod( obj } ) + #' @rdname int_methods setMethod( "content_indent_mod<-", "VTableNodeInfo", @@ -1558,21 +1650,28 @@ setMethod( #' @rdname int_methods #' @export setGeneric("rawvalues", function(obj) standardGeneric("rawvalues")) + #' @rdname int_methods setMethod("rawvalues", "ValueWrapper", function(obj) obj@value) + #' @rdname int_methods setMethod("rawvalues", "LevelComboSplitValue", function(obj) obj@combolevels) + #' @rdname int_methods setMethod("rawvalues", "list", function(obj) lapply(obj, rawvalues)) + #' @rdname int_methods setMethod("rawvalues", "ANY", function(obj) obj) + #' @rdname int_methods setMethod("rawvalues", "CellValue", function(obj) obj[[1]]) + #' @rdname int_methods setMethod( "rawvalues", "TreePos", function(obj) rawvalues(pos_splvals(obj)) ) + #' @rdname int_methods setMethod( "rawvalues", "RowsVerticalSection", @@ -1582,31 +1681,37 @@ setMethod( #' @rdname int_methods #' @export setGeneric("value_names", function(obj) standardGeneric("value_names")) + #' @rdname int_methods setMethod( "value_names", "ANY", function(obj) as.character(rawvalues(obj)) ) + #' @rdname int_methods setMethod( "value_names", "TreePos", function(obj) value_names(pos_splvals(obj)) ) + #' @rdname int_methods setMethod( "value_names", "list", function(obj) lapply(obj, value_names) ) + #' @rdname int_methods setMethod( "value_names", "ValueWrapper", function(obj) rawvalues(obj) ) + #' @rdname int_methods setMethod( "value_names", "LevelComboSplitValue", function(obj) obj@value ) ## obj@comboname) + #' @rdname int_methods setMethod( "value_names", "RowsVerticalSection", @@ -1617,13 +1722,16 @@ setMethod( ## XXX #' @rdname int_methods setGeneric("value_labels", function(obj) standardGeneric("value_labels")) + #' @rdname int_methods setMethod("value_labels", "ANY", function(obj) as.character(obj_label(obj))) + #' @rdname int_methods setMethod( "value_labels", "TreePos", function(obj) sapply(pos_splvals(obj), obj_label) ) + #' @rdname int_methods setMethod("value_labels", "list", function(obj) { ret <- lapply(obj, obj_label) @@ -1641,20 +1749,21 @@ setMethod( function(obj) setNames(attr(obj, "row_labels", exact = TRUE), value_names(obj)) ) - #' @rdname int_methods setMethod("value_labels", "ValueWrapper", function(obj) obj_label(obj)) + #' @rdname int_methods setMethod( "value_labels", "LevelComboSplitValue", function(obj) obj_label(obj) ) + #' @rdname int_methods setMethod("value_labels", "MultiVarSplit", function(obj) obj@var_labels) - #' @rdname int_methods setGeneric("spl_varlabels", function(obj) standardGeneric("spl_varlabels")) + #' @rdname int_methods setMethod("spl_varlabels", "MultiVarSplit", function(obj) obj@var_labels) @@ -1663,15 +1772,13 @@ setGeneric( "spl_varlabels<-", function(object, value) standardGeneric("spl_varlabels<-") ) + #' @rdname int_methods setMethod("spl_varlabels<-", "MultiVarSplit", function(object, value) { object@var_labels <- value object }) - - - ## These two are similar enough we could probably combine ## them but conceptually they are pretty different ## split_exargs is a list of extra arguments that apply @@ -1680,6 +1787,7 @@ setMethod("spl_varlabels<-", "MultiVarSplit", function(object, value) { ## associated with specific values of the split #' @rdname int_methods setGeneric("splv_extra", function(obj) standardGeneric("splv_extra")) + #' @rdname int_methods setMethod( "splv_extra", "SplitValue", @@ -1700,11 +1808,9 @@ setMethod( } ) - - - #' @rdname int_methods setGeneric("split_exargs", function(obj) standardGeneric("split_exargs")) + #' @rdname int_methods setMethod( "split_exargs", "Split", @@ -1716,6 +1822,7 @@ setGeneric( "split_exargs<-", function(obj, value) standardGeneric("split_exargs<-") ) + #' @rdname int_methods setMethod( "split_exargs<-", "Split", @@ -1725,7 +1832,6 @@ setMethod( } ) - is_labrow <- function(obj) is(obj, "LabelRow") spl_ref_group <- function(obj) { @@ -1735,22 +1841,21 @@ spl_ref_group <- function(obj) { ### column info - #' Column information/structure accessors #' #' @inheritParams gen_args -#' @param df data.frame/NULL. Data to use if the column information is being -#' generated from a Pre-Data layout object -#' @param path character or NULL. `col_counts` getter and setter only. +#' @param df (`data.frame` or `NULL`)\cr data to use if the column information is being +#' generated from a pre-data layout object. +#' @param path (`character` or `NULL`)\cr `col_counts` accessor and setter only. #' Path (in column structure). -#' @param rtpos `TreePos`. Root position. +#' @param rtpos (`TreePos`)\cr root position. #' -#' @return A \code{LayoutColTree} object. +#' @return A `LayoutColTree` object. #' #' @rdname col_accessors -#' #' @export setGeneric("clayout", function(obj) standardGeneric("clayout")) + #' @rdname col_accessors #' @exportMethod clayout setMethod( @@ -1770,10 +1875,6 @@ setMethod( #' @exportMethod clayout setMethod("clayout", "ANY", function(obj) PreDataColLayout()) - - - - #' @rdname col_accessors #' @export setGeneric("clayout<-", function(object, value) standardGeneric("clayout<-")) @@ -1788,7 +1889,6 @@ setMethod( } ) - #' @rdname col_accessors #' @export setGeneric("col_info", function(obj) standardGeneric("col_info")) @@ -1806,9 +1906,11 @@ setMethod( #' @rdname col_accessors #' @export setGeneric("col_info<-", function(obj, value) standardGeneric("col_info<-")) -#' @rdname col_accessors -#' @return Various column information, depending on the accessor used. + +#' @return Returns various information about columns, depending on the accessor used. +#' #' @exportMethod col_info<- +#' @rdname col_accessors setMethod( "col_info<-", "TableRow", function(obj, value) { @@ -1854,10 +1956,6 @@ setMethod( } ) - - - - #' @rdname col_accessors #' @export setGeneric( @@ -1865,7 +1963,6 @@ setGeneric( function(obj, df = NULL, rtpos = TreePos()) standardGeneric("coltree") ) - #' @rdname col_accessors #' @exportMethod coltree setMethod( @@ -1880,7 +1977,6 @@ setMethod( #' @rdname col_accessors #' @export coltree - setMethod( "coltree", "PreDataTableLayouts", function(obj, df, rtpos) coltree(clayout(obj), df, rtpos) @@ -1917,7 +2013,6 @@ setMethod( } ) - #' @rdname col_accessors #' @export coltree setMethod( @@ -1958,7 +2053,6 @@ setMethod( } ) - #' @rdname col_accessors #' @export setGeneric("col_exprs", function(obj, df = NULL) standardGeneric("col_exprs")) @@ -1997,6 +2091,7 @@ setMethod( #' @rdname int_methods setGeneric("col_extra_args", function(obj, df = NULL) standardGeneric("col_extra_args")) + #' @rdname int_methods setMethod( "col_extra_args", "InstantiatedColumnInfo", @@ -2007,11 +2102,13 @@ setMethod( obj@cextra_args } ) + #' @rdname int_methods setMethod( "col_extra_args", "PreDataTableLayouts", function(obj, df) col_extra_args(clayout(obj), df) ) + #' @rdname int_methods setMethod( "col_extra_args", "PreDataColLayout", @@ -2019,6 +2116,7 @@ setMethod( col_extra_args(coltree(obj, df), NULL) } ) + #' @rdname int_methods setMethod( "col_extra_args", "LayoutColTree", @@ -2029,6 +2127,7 @@ setMethod( get_col_extras(obj) } ) + #' @rdname int_methods setMethod( "col_extra_args", "LayoutColLeaf", @@ -2041,11 +2140,6 @@ setMethod( } ) - - - - - #' @export #' @rdname col_accessors setGeneric("col_counts", function(obj, path = NULL) standardGeneric("col_counts")) @@ -2090,8 +2184,6 @@ setMethod( } ) - - #' @export #' @rdname col_accessors setGeneric("col_total", function(obj) standardGeneric("col_total")) @@ -2136,28 +2228,27 @@ setMethod( } ) - - - - - #' @rdname int_methods setGeneric("disp_ccounts", function(obj) standardGeneric("disp_ccounts")) + #' @rdname int_methods setMethod( "disp_ccounts", "VTableTree", function(obj) disp_ccounts(col_info(obj)) ) + #' @rdname int_methods setMethod( "disp_ccounts", "InstantiatedColumnInfo", function(obj) obj@display_columncounts ) + #' @rdname int_methods setMethod( "disp_ccounts", "PreDataTableLayouts", function(obj) disp_ccounts(clayout(obj)) ) + #' @rdname int_methods setMethod( "disp_ccounts", "PreDataColLayout", @@ -2166,6 +2257,7 @@ setMethod( #' @rdname int_methods setGeneric("disp_ccounts<-", function(obj, value) standardGeneric("disp_ccounts<-")) + #' @rdname int_methods setMethod( "disp_ccounts<-", "VTableTree", @@ -2176,6 +2268,7 @@ setMethod( obj } ) + #' @rdname int_methods setMethod( "disp_ccounts<-", "InstantiatedColumnInfo", @@ -2184,6 +2277,7 @@ setMethod( obj } ) + #' @rdname int_methods setMethod( "disp_ccounts<-", "PreDataColLayout", @@ -2192,6 +2286,7 @@ setMethod( obj } ) + #' @rdname int_methods setMethod( "disp_ccounts<-", "LayoutColTree", @@ -2200,6 +2295,7 @@ setMethod( obj } ) + #' @rdname int_methods setMethod( "disp_ccounts<-", "PreDataTableLayouts", @@ -2214,24 +2310,28 @@ setMethod( #' @rdname int_methods #' @export setGeneric("colcount_format", function(obj) standardGeneric("colcount_format")) + #' @rdname int_methods #' @export setMethod( "colcount_format", "InstantiatedColumnInfo", function(obj) obj@columncount_format ) + #' @rdname int_methods #' @export setMethod( "colcount_format", "VTableNodeInfo", function(obj) colcount_format(col_info(obj)) ) + #' @rdname int_methods #' @export setMethod( "colcount_format", "PreDataColLayout", function(obj) obj@columncount_format ) + #' @rdname int_methods #' @export setMethod( @@ -2245,6 +2345,7 @@ setGeneric( "colcount_format<-", function(obj, value) standardGeneric("colcount_format<-") ) + #' @export #' @rdname int_methods setMethod( @@ -2254,6 +2355,7 @@ setMethod( obj } ) + #' @rdname int_methods #' @export setMethod( @@ -2265,6 +2367,7 @@ setMethod( obj } ) + #' @rdname int_methods #' @export setMethod( @@ -2274,6 +2377,7 @@ setMethod( obj } ) + #' @rdname int_methods #' @export setMethod( @@ -2286,15 +2390,15 @@ setMethod( } ) - -#' Exported for use in tern +#' Exported for use in `tern` #' #' Does the `table`/`row`/`InstantiatedColumnInfo` object contain no column structure information? #' #' @inheritParams gen_args +#' +#' @return `TRUE` if the object has no/empty instantiated column information, `FALSE` otherwise. +#' #' @rdname no_info -#' @return \code{TRUE} if the object has no/empty instantiated column information, -#' \code{FALSE} otherwise. #' @export setGeneric("no_colinfo", function(obj) standardGeneric("no_colinfo")) @@ -2312,15 +2416,18 @@ setMethod( function(obj) length(obj@subset_exprs) == 0 ) ## identical(obj, EmptyColInfo)) - #' Names of a `TableTree` #' -#' @param x the object. -#' @details For `TableTrees` with more than one level of splitting in columns, the names are defined to be the top-level -#' split values repped out across the columns that they span. -#' @rdname names -#' @return The column names of \code{x}, as defined in the details above. +#' @param x (`TableTree`)\cr the object. +#' +#' @details +#' For `TableTree`s with more than one level of splitting in columns, the names are defined to be the top-level +#' split values repped out across the columns that they span. +#' +#' @return The column names of `x`, as defined in the details above. +#' #' @exportMethod names +#' @rdname names setMethod( "names", "VTableNodeInfo", function(x) names(col_info(x)) @@ -2328,11 +2435,11 @@ setMethod( #' @rdname names #' @exportMethod names - setMethod( "names", "InstantiatedColumnInfo", function(x) names(coltree(x)) ) + #' @rdname names #' @exportMethod names setMethod( @@ -2360,22 +2467,21 @@ setMethod( } ) - - - -#' convert to a vector +#' Convert to a vector +#' +#' Convert an `rtables` framework object into a vector, if possible. This is unlikely to be useful in +#' realistic scenarios. #' -#' Convert an `rtables` framework object into a vector, if possible. -#' This is unlikely to be useful in realistic scenarios. +#' @param x (`ANY`)\cr the object to be converted to a vector. +#' @param mode (`string`)\cr passed on to [as.vector()]. #' -#' @note This only works for a table with a single row or a row object. +#' @return A vector of the chosen mode (or an error is raised if more than one row was present). +#' +#' @note This only works for a table with a single row or a row object. #' #' @name asvec -#' @param x ANY. The object to be converted to a vector -#' @param mode character(1). Passed on to \code{\link[base]{as.vector}} -#' @return a vector of the chosen mode (or an error is raised if more than one row was present). -#' @exportMethod as.vector #' @aliases as.vector,VTableTree-method +#' @exportMethod as.vector setMethod("as.vector", "VTableTree", function(x, mode) { stopifnot(nrow(x) == 1L) if (nrow(content_table(x)) == 1L) { @@ -2386,10 +2492,12 @@ setMethod("as.vector", "VTableTree", function(x, mode) { as.vector(tree_children(tab)[[1]], mode = mode) }) -#' @exportMethod as.vector #' @inheritParams asvec +#' #' @rdname int_methods +#' @exportMethod as.vector setMethod("as.vector", "TableRow", function(x, mode) as.vector(unlist(row_values(x)), mode = mode)) + #' @rdname int_methods #' @exportMethod as.vector setMethod("as.vector", "ElementaryTable", function(x, mode) { @@ -2397,9 +2505,11 @@ setMethod("as.vector", "ElementaryTable", function(x, mode) { as.vector(tree_children(x)[[1]], mode = mode) }) -## cuts +## cuts ---- + #' @rdname int_methods setGeneric("spl_cuts", function(obj) standardGeneric("spl_cuts")) + #' @rdname int_methods setMethod( "spl_cuts", "VarStaticCutSplit", @@ -2408,6 +2518,7 @@ setMethod( #' @rdname int_methods setGeneric("spl_cutlabels", function(obj) standardGeneric("spl_cutlabels")) + #' @rdname int_methods setMethod( "spl_cutlabels", "VarStaticCutSplit", @@ -2416,6 +2527,7 @@ setMethod( #' @rdname int_methods setGeneric("spl_cutfun", function(obj) standardGeneric("spl_cutfun")) + #' @rdname int_methods setMethod( "spl_cutfun", "VarDynCutSplit", @@ -2424,6 +2536,7 @@ setMethod( #' @rdname int_methods setGeneric("spl_cutlabelfun", function(obj) standardGeneric("spl_cutlabelfun")) + #' @rdname int_methods setMethod( "spl_cutlabelfun", "VarDynCutSplit", @@ -2432,6 +2545,7 @@ setMethod( #' @rdname int_methods setGeneric("spl_is_cmlcuts", function(obj) standardGeneric("spl_is_cmlcuts")) + #' @rdname int_methods setMethod( "spl_is_cmlcuts", "VarDynCutSplit", @@ -2443,6 +2557,7 @@ setGeneric( "spl_varnames", function(obj) standardGeneric("spl_varnames") ) + #' @rdname int_methods setMethod( "spl_varnames", "MultiVarSplit", @@ -2454,6 +2569,7 @@ setGeneric( "spl_varnames<-", function(object, value) standardGeneric("spl_varnames<-") ) + #' @rdname int_methods setMethod( "spl_varnames<-", "MultiVarSplit", @@ -2468,32 +2584,37 @@ setMethod( } ) - -#' Top Left Material (Experimental) +#' Top left material +#' +#' A `TableTree` object can have *top left material* which is a sequence of strings which are printed in the +#' area of the table between the column header display and the label of the first row. These functions access +#' and modify that material. +#' #' @inheritParams gen_args -#' @description A `TableTree` object can have \emph{top left material} which is a sequence -#' of strings which are printed in the area of the table between the column header display -#' and the label of the first row. These functions access and modify that material. #' -#' @return A character vector representing the top-left material of \code{obj} (or -#' \code{obj} after modification, in the case of the setter). +#' @return A character vector representing the top-left material of `obj` (or `obj` after modification, in the +#' case of the setter). +#' #' @export #' @rdname top_left setGeneric("top_left", function(obj) standardGeneric("top_left")) + #' @export #' @rdname top_left setMethod("top_left", "VTableTree", function(obj) top_left(col_info(obj))) + #' @export #' @rdname top_left setMethod("top_left", "InstantiatedColumnInfo", function(obj) obj@top_left) + #' @export #' @rdname top_left setMethod("top_left", "PreDataTableLayouts", function(obj) obj@top_left) - #' @export #' @rdname top_left setGeneric("top_left<-", function(obj, value) standardGeneric("top_left<-")) + #' @export #' @rdname top_left setMethod("top_left<-", "VTableTree", function(obj, value) { @@ -2502,6 +2623,7 @@ setMethod("top_left<-", "VTableTree", function(obj, value) { col_info(obj) <- cinfo obj }) + #' @export #' @rdname top_left setMethod("top_left<-", "InstantiatedColumnInfo", function(obj, value) { @@ -2516,7 +2638,6 @@ setMethod("top_left<-", "PreDataTableLayouts", function(obj, value) { obj }) - vil_collapse <- function(x) { x <- unlist(x) x <- x[!is.na(x)] @@ -2524,30 +2645,25 @@ vil_collapse <- function(x) { x[nzchar(x)] } -#' List Variables required by a pre-data table layout -#' -#' @param lyt The Layout (or a component thereof) +#' List variables required by a pre-data table layout #' -#' @details This will walk the layout declaration and return a vector -#' of the names of the unique variables that are used in any of -#' the following ways: +#' @param lyt (`PreDataTableLayouts`)\cr the layout (or a component thereof). #' -#' \itemize{ -#' \item{Variable being split on (directly or via cuts)} -#' \item{Element of a Multi-variable column split} -#' \item{Content variable} -#' \item{Value-label variable} -#' } +#' @details +#' This will walk the layout declaration and return a vector of the names of the unique variables that are used +#' in any of the following ways: #' -#' @note This function will not detect dependencies implicit in -#' analysis or summary functions which accept \code{x} or \code{df} and then -#' rely on the existence of particular variables not being split on/ -#' analyzed. +#' * Variable being split on (directly or via cuts) +#' * Element of a Multi-variable column split +#' * Content variable +#' * Value-label variable #' -#' @note The order these variable names appear within the return vector -#' is undefined and should not be relied upon. +#' @return A character vector containing the unique variables explicitly used in the layout (see the notes below). #' -#' @return A character vector containing the unique variables explicitly used in the layout (see Notes). +#' @note +#' * This function will not detect dependencies implicit in analysis or summary functions which accept `x` +#' or `df` and then rely on the existence of particular variables not being split on/analyzed. +#' * The order these variable names appear within the return vector is undefined and should not be relied upon. #' #' @examples #' lyt <- basic_table() %>% @@ -2620,11 +2736,8 @@ setMethod( function(lyt) character() ) +## Titles and footers ---- - - - -## Titles and footers # ##' Titles and Footers # ##' # ##' Get or set the titles and footers on an object @@ -2659,15 +2772,15 @@ setMethod( function(obj) "" ) -##' @rdname formatters_methods -##' @export +#' @rdname formatters_methods +#' @export setMethod( "subtitles", "VTitleFooter", function(obj) obj@subtitles ) -##' @rdname formatters_methods -##' @export +#' @rdname formatters_methods +#' @export setMethod( "subtitles<-", "VTitleFooter", function(obj, value) { @@ -2676,23 +2789,22 @@ setMethod( } ) -##' @rdname formatters_methods -##' @export +#' @rdname formatters_methods +#' @export setMethod( "subtitles", "TableRow", # Only getter: see main_title for TableRow function(obj) character() ) -##' @rdname formatters_methods -##' @export +#' @rdname formatters_methods +#' @export setMethod( "main_footer", "VTitleFooter", function(obj) obj@main_footer ) - -##' @rdname formatters_methods -##' @export +#' @rdname formatters_methods +#' @export setMethod( "main_footer<-", "VTitleFooter", function(obj, value) { @@ -2701,24 +2813,22 @@ setMethod( } ) -##' @rdname formatters_methods -##' @export +#' @rdname formatters_methods +#' @export setMethod( "main_footer", "TableRow", # Only getter: see main_title for TableRow function(obj) character() ) - -##' @rdname formatters_methods -##' @export +#' @rdname formatters_methods +#' @export setMethod( "prov_footer", "VTitleFooter", function(obj) obj@provenance_footer ) - -##' @rdname formatters_methods -##' @export +#' @rdname formatters_methods +#' @export setMethod( "prov_footer<-", "VTitleFooter", function(obj, value) { @@ -2727,14 +2837,13 @@ setMethod( } ) -##' @rdname formatters_methods -##' @export +#' @rdname formatters_methods +#' @export setMethod( "prov_footer", "TableRow", # Only getter: see main_title for TableRow function(obj) character() ) - make_ref_value <- function(value) { if (is(value, "RefFootnote")) { value <- list(value) @@ -2744,22 +2853,23 @@ make_ref_value <- function(value) { value } - -#' Referential Footnote Accessors +#' Referential footnote accessors #' -#' Get and set referential footnotes on aspects of a built table +#' Access and set the referential footnotes aspects of a built table. #' #' @inheritParams gen_args +#' #' @export #' @rdname ref_fnotes - setGeneric("row_footnotes", function(obj) standardGeneric("row_footnotes")) + #' @export #' @rdname int_methods setMethod( "row_footnotes", "TableRow", function(obj) obj@row_footnotes ) + #' @export #' @rdname int_methods setMethod( @@ -2770,6 +2880,7 @@ setMethod( #' @export #' @rdname ref_fnotes setGeneric("row_footnotes<-", function(obj, value) standardGeneric("row_footnotes<-")) + #' @export #' @rdname int_methods setMethod( @@ -2780,7 +2891,6 @@ setMethod( } ) - #' @export #' @rdname int_methods setMethod( @@ -2795,12 +2905,14 @@ setMethod( #' @export #' @rdname ref_fnotes setGeneric("cell_footnotes", function(obj) standardGeneric("cell_footnotes")) + #' @export #' @rdname int_methods setMethod( "cell_footnotes", "CellValue", function(obj) attr(obj, "footnotes", exact = TRUE) %||% list() ) + #' @export #' @rdname int_methods setMethod( @@ -2834,10 +2946,10 @@ setMethod( } ) - #' @export #' @rdname ref_fnotes setGeneric("cell_footnotes<-", function(obj, value) standardGeneric("cell_footnotes<-")) + #' @export #' @rdname int_methods setMethod( @@ -2880,10 +2992,12 @@ setMethod("cell_footnotes<-", "ContentRow", definition = .cfn_set_helper ) -# Deprecated methods +# Deprecated methods ---- + #' @export #' @rdname ref_fnotes setGeneric("col_fnotes_here", function(obj) standardGeneric("col_fnotes_here")) + #' @export #' @rdname ref_fnotes setMethod("col_fnotes_here", "ANY", function(obj) { @@ -2894,9 +3008,11 @@ setMethod("col_fnotes_here", "ANY", function(obj) { ) col_footnotes(obj) }) + #' @export #' @rdname ref_fnotes setGeneric("col_fnotes_here<-", function(obj, value) standardGeneric("col_fnotes_here<-")) + #' @export #' @rdname int_methods setMethod("col_fnotes_here<-", "ANY", function(obj, value) { @@ -2961,6 +3077,7 @@ setMethod( #' @export #' @rdname ref_fnotes setGeneric("ref_index", function(obj) standardGeneric("ref_index")) + #' @export #' @rdname int_methods setMethod( @@ -2971,6 +3088,7 @@ setMethod( #' @export #' @rdname ref_fnotes setGeneric("ref_index<-", function(obj, value) standardGeneric("ref_index<-")) + #' @export #' @rdname int_methods setMethod( @@ -2981,10 +3099,10 @@ setMethod( } ) - #' @export #' @rdname ref_fnotes setGeneric("ref_symbol", function(obj) standardGeneric("ref_symbol")) + #' @export #' @rdname int_methods setMethod( @@ -2995,6 +3113,7 @@ setMethod( #' @export #' @rdname ref_fnotes setGeneric("ref_symbol<-", function(obj, value) standardGeneric("ref_symbol<-")) + #' @export #' @rdname int_methods setMethod( @@ -3005,10 +3124,10 @@ setMethod( } ) - #' @export #' @rdname ref_fnotes setGeneric("ref_msg", function(obj) standardGeneric("ref_msg")) + #' @export #' @rdname int_methods setMethod( @@ -3016,7 +3135,6 @@ setMethod( function(obj) obj@value ) - setGeneric(".fnote_set_inner<-", function(ttrp, colpath, value) standardGeneric(".fnote_set_inner<-")) setMethod( @@ -3047,7 +3165,6 @@ setMethod( } ) - setMethod( ".fnote_set_inner<-", c("VTableTree", "ANY"), function(ttrp, colpath, value) { @@ -3067,13 +3184,12 @@ setMethod( } ) - -#' @param rowpath character or NULL. Path within row structure. \code{NULL} -#' indicates the footnote should go on the column rather than cell. -#' @param colpath character or NULL. Path within column structure. \code{NULL} -#' indicates footnote should go on the row rather than cell -#' @param reset_idx logical(1). Should the numbering for referential footnotes -#' be immediately recalculated. Defaults to TRUE. +#' @param rowpath (`character` or `NULL`)\cr path within row structure. `NULL` indicates the footnote should +#' go on the column rather than cell. +#' @param colpath (`character` or `NULL`)\cr path within column structure. `NULL` indicates footnote should go +#' on the row rather than cell. +#' @param reset_idx (`flag`)\cr whether the numbering for referential footnotes should be immediately +#' recalculated. Defaults to `TRUE`. #' #' @examples #' # How to add referencial footnotes after having created a table @@ -3094,8 +3210,7 @@ setMethod( #' fnotes_at_path(tbl, rowpath = c("SEX", "UNDIFFERENTIATED")) <- "Unfamous paper 2" #' # tbl #' -#' @seealso [row_paths()], [col_paths()], -#' [row_paths_summary()], [col_paths_summary()] +#' @seealso [row_paths()], [col_paths()], [row_paths_summary()], [col_paths_summary()] #' #' @export #' @rdname ref_fnotes @@ -3109,6 +3224,7 @@ setGeneric("fnotes_at_path<-", function(obj, ## non-null rowpath, null or non-null colpath #' @inheritParams fnotes_at_path<- +#' #' @export #' @rdname int_methods setMethod( @@ -3143,10 +3259,10 @@ setMethod( } ) - setGeneric("has_force_pag", function(obj) standardGeneric("has_force_pag")) setMethod("has_force_pag", "TableTree", function(obj) !is.na(ptitle_prefix(obj))) + setMethod("has_force_pag", "Split", function(obj) !is.na(ptitle_prefix(obj))) setMethod("has_force_pag", "VTableNodeInfo", function(obj) FALSE) @@ -3154,6 +3270,7 @@ setMethod("has_force_pag", "VTableNodeInfo", function(obj) FALSE) setGeneric("ptitle_prefix", function(obj) standardGeneric("ptitle_prefix")) setMethod("ptitle_prefix", "TableTree", function(obj) obj@page_title_prefix) + setMethod("ptitle_prefix", "Split", function(obj) obj@page_title_prefix) setMethod("ptitle_prefix", "ANY", function(obj) NULL) @@ -3165,16 +3282,17 @@ setMethod("page_titles<-", "VTableTree", function(obj, value) { obj }) - ## Horizontal separator -------------------------------------------------------- + #' Access or recursively set header-body separator for tables #' #' @inheritParams gen_args -#' @param value character(1). String to use as new header/body separator. +#' @param value (`string`)\cr string to use as new header/body separator. #' -#' @return for `horizontal_sep` the string acting as the header separator. -#' for `horizontal_sep<-`, the `obj`, with the new header separator -#' applied recursively to it and all its subtables. +#' @return +#' * `horizontal_sep` returns the string acting as the header separator. +#' * `horizontal_sep<-` returns `obj`, with the new header separator applied recursively to it and all its +#' subtables. #' #' @export setGeneric("horizontal_sep", function(obj) standardGeneric("horizontal_sep")) @@ -3190,7 +3308,6 @@ setMethod( #' @export setGeneric("horizontal_sep<-", function(obj, value) standardGeneric("horizontal_sep<-")) - #' @rdname horizontal_sep #' @export setMethod( @@ -3220,16 +3337,18 @@ setMethod( function(obj, value) obj ) - ## Section dividers ------------------------------------------------------------ + # Used for splits setGeneric("spl_section_div", function(obj) standardGeneric("spl_section_div")) + setMethod( "spl_section_div", "Split", function(obj) obj@child_section_div ) setGeneric("spl_section_div<-", function(obj, value) standardGeneric("spl_section_div<-")) + setMethod( "spl_section_div<-", "Split", function(obj, value) { @@ -3258,9 +3377,8 @@ setMethod("trailing_section_div<-", "TableRow", function(obj, value) { obj }) -#' @title Section dividers getter and setter +#' Section dividers accessor and setter #' -#' @description #' `section_div` can be used to set or get the section divider for a table object #' produced by [build_table()]. When assigned in post-processing (`section_div<-`) #' the table can have a section divider after every row, each assigned independently. @@ -3268,13 +3386,13 @@ setMethod("trailing_section_div<-", "TableRow", function(obj, value) { #' splits) and [analyze()] have a `section_div` parameter that will produce separators #' between split sections and data subgroups, respectively. #' -#' @param obj Table object. This can be of any class that inherits from `VTableTree` +#' @param obj (`VTableTree`)\cr table object. This can be of any class that inherits from `VTableTree` #' or `TableRow`/`LabelRow`. -#' @param only_sep_sections logical(1). Defaults to `FALSE` for `section_div<-`. Allows +#' @param only_sep_sections (`flag`)\cr defaults to `FALSE` for `section_div<-`. Allows #' you to set the section divider only for sections that are splits or analyses if the number of #' values is less than the number of rows in the table. If `TRUE`, the section divider will #' be set for all rows of the table. -#' @param value character. Vector of single characters to use as section dividers. Each character +#' @param value (`character`)\cr vector of single characters to use as section dividers. Each character #' is repeated such that all section dividers span the width of the table. Each character that is #' not `NA_character_` will produce a trailing separator for each row of the table. `value` length #' should reflect the number of rows, or be between 1 and the number of splits/levels. @@ -3351,11 +3469,13 @@ setMethod("section_div", "VTableTree", function(obj) { unname(section_div(tree_children(obj))) } }) + #' @rdname section_div #' @aliases section_div,list-method setMethod("section_div", "list", function(obj) { unlist(lapply(obj, section_div)) }) + #' @rdname section_div #' @aliases section_div,TableRow-method setMethod("section_div", "TableRow", function(obj) { @@ -3414,6 +3534,7 @@ setMethod("section_div<-", "VTableTree", function(obj, only_sep_sections = FALSE } obj }) + #' @rdname section_div #' @aliases section_div<-,list-method setMethod("section_div<-", "list", function(obj, only_sep_sections = FALSE, value) { @@ -3433,12 +3554,14 @@ setMethod("section_div<-", "list", function(obj, only_sep_sections = FALSE, valu } obj }) + #' @rdname section_div #' @aliases section_div<-,TableRow-method setMethod("section_div<-", "TableRow", function(obj, only_sep_sections = FALSE, value) { trailing_section_div(obj) <- value obj }) + #' @rdname section_div #' @aliases section_div<-,LabelRow-method setMethod("section_div<-", "LabelRow", function(obj, only_sep_sections = FALSE, value) { @@ -3474,6 +3597,7 @@ setMethod( "header_section_div", "PreDataTableLayouts", function(obj) obj@header_section_div ) + #' @rdname section_div #' @aliases header_section_div,PreDataTableLayouts-method setMethod( @@ -3495,6 +3619,7 @@ setMethod( obj } ) + #' @rdname section_div #' @aliases header_section_div<-,PreDataTableLayouts-method setMethod( @@ -3505,6 +3630,7 @@ setMethod( obj } ) + .check_header_section_div <- function(chr) { if (!is.na(chr) && (!is.character(chr) || length(chr) > 1 || nchar(chr) > 1 || nchar(chr) == 0)) { stop("header_section_div must be a single character or NA_character_ if not used") @@ -3539,6 +3665,7 @@ setMethod( ) ## table_inset ---------------------------------------------------------- + #' @rdname formatters_methods #' @export setMethod( diff --git a/R/tt_afun_utils.R b/R/tt_afun_utils.R index db112d7ae..5ebd80992 100644 --- a/R/tt_afun_utils.R +++ b/R/tt_afun_utils.R @@ -1,23 +1,21 @@ -#' @title Cell value constructors +#' Cell value constructors #' -#' @description Construct a cell value and associate formatting, labeling, -#' indenting, and column spanning information with it. +#' Construct a cell value and associate formatting, labeling, indenting, and column spanning information with it. #' #' @inheritParams compat_args #' @inheritParams lyt_args -#' @param x ANY. Cell value. -#' @param format character(1) or function. The format label (string) or -#' `formatters` function to apply to `x`. See -#' [formatters::list_valid_format_labels()] for currently supported -#' format labels. -#' @param label character(1). Label or `NULL`. If non-null, it will be looked at -#' when determining row labels. -#' @param colspan integer(1). Column span value. -#' @param footnotes list or `NULL`. Referential footnote messages for the cell. -#' @note Currently column spanning is only supported for defining header -#' structure. -#' @rdname rcell +#' @param x (`ANY`)\cr cell value. +#' @param format (`string` or `function`)\cr the format label (string) or `formatters` function to apply to `x`. +#' See [formatters::list_valid_format_labels()] for currently supported format labels. +#' @param label (`string` or `NULL`)\cr label. If non-`NULL`, it will be looked at when determining row labels. +#' @param colspan (`integer(1)`)\cr column span value. +#' @param footnotes (`list` or `NULL`)\cr referential footnote messages for the cell. +#' #' @inherit CellValue return +#' +#' @note Currently column spanning is only supported for defining header structure. +#' +#' @rdname rcell #' @export rcell <- function(x, format = NULL, @@ -77,14 +75,14 @@ rcell <- function(x, ret } -#' @details \code{non_ref_rcell} provides the common \emph{blank for cells in -#' the reference column, this value otherwise}, and should be passed the value -#' of \code{.in_ref_col} when it is used. -#' -#' @param is_ref logical(1). Are we in the reference column (i.e. -#' .in_ref_col should be passed to this argument) -#' @param refval ANY. Value to use when in the reference column. Defaults -#' to \code{NULL} +#' @param is_ref (`flag`)\cr whether function is being used in the reference column (i.e. `.in_ref_col` should be +#' passed to this argument). +#' @param refval (`ANY`)\cr value to use when in the reference column. Defaults to `NULL`. +#' +#' @details +#' `non_ref_rcell` provides the common *blank for cells in the reference column, this value otherwise*, and should +#' be passed the value of `.in_ref_col` when it is used. +#' #' @rdname rcell #' @export non_ref_rcell <- function(x, is_ref, format = NULL, colspan = 1L, @@ -100,36 +98,28 @@ non_ref_rcell <- function(x, is_ref, format = NULL, colspan = 1L, ) } - #' Create multiple rows in analysis or summary functions #' -#' define the cells that get placed into multiple rows in `afun` -#' -#' -#' @param ... single row defining expressions -#' @param .list list. list cell content, usually `rcells`, the `.list` is -#' concatenated to `...` -#' @param .names character or NULL. Names of the returned list/structure. -#' @param .labels character or NULL. labels for the defined rows -#' @param .formats character or NULL. Formats for the values -#' @param .indent_mods integer or NULL. Indent modifications for the defined -#' rows. -#' @param .cell_footnotes list. Referential footnote messages to be associated -#' by name with \emph{cells}. -#' @param .row_footnotes list. Referential footnotes messages to be associated -#' by name with \emph{rows}. -#' @param .aligns character or NULL. Alignments for the cells. Standard for `NULL` -#' is `"center"`. See [formatters::list_valid_aligns()] for currently supported -#' alignments. -#' @param .format_na_strs character or NULL. NA strings for the cells -#' -#' @note -#' In post-processing, referential footnotes can also be added using row and column +#' Define the cells that get placed into multiple rows in `afun`. +#' +#' @param ... single row defining expressions. +#' @param .list (`list`)\cr list cell content (usually `rcells`). The `.list` is concatenated to `...`. +#' @param .names (`character` or `NULL`)\cr names of the returned list/structure. +#' @param .labels (`character` or `NULL`)\cr labels for the defined rows. +#' @param .formats (`character` or `NULL`)\cr formats for the values. +#' @param .indent_mods (`integer` or `NULL`)\cr indent modifications for the defined rows. +#' @param .cell_footnotes (`list`)\cr referential footnote messages to be associated by name with *cells*. +#' @param .row_footnotes (`list`)\cr referential footnotes messages to be associated by name with *rows*. +#' @param .aligns (`character` or `NULL`)\cr alignments for the cells. Standard for `NULL` is `"center"`. +#' See [formatters::list_valid_aligns()] for currently supported alignments. +#' @param .format_na_strs (`character` or `NULL`)\cr NA strings for the cells. +#' +#' @note In post-processing, referential footnotes can also be added using row and column #' paths with [`fnotes_at_path<-`]. #' -#' @export -#' @return an \code{RowsVerticalSection} object (or \code{NULL}). The details of -#' this object should be considered an internal implementation detail. +#' @return A `RowsVerticalSection` object (or `NULL`). The details of this object should be considered an +#' internal implementation detail. +#' #' @seealso [analyze()] #' #' @examples @@ -152,6 +142,7 @@ non_ref_rcell <- function(x, is_ref, format = NULL, colspan = 1L, #' tbl <- build_table(lyt, ex_adsl) #' tbl #' +#' @export in_rows <- function(..., .list = NULL, .names = NULL, .labels = NULL, .formats = NULL, @@ -175,7 +166,6 @@ in_rows <- function(..., .list = NULL, .names = NULL, stopifnot(!anyNA(.names)) } - if (length(l) == 0) { if ( length(.labels) > 0 || @@ -259,12 +249,9 @@ in_rows <- function(..., .list = NULL, .names = NULL, ## names(l2) <- names(l) if (length(ret) == 0) NULL else ret - ## if (length(l) == 0) NULL else l } - - .validate_nms <- function(vals, .stats, arg) { if (!is.null(arg)) { if (is.null(names(arg))) { @@ -278,44 +265,32 @@ in_rows <- function(..., .list = NULL, .names = NULL, arg } - -#' Create custom analysis function wrapping existing function -#' -#' @param fun function. The function to be wrapped in a new customized analysis -#' fun. Should return named list. -#' @param .stats character. Names of elements to keep from \code{fun}'s full -#' output. -#' @param .formats ANY. vector/list of formats to override any defaults applied -#' by \code{fun}. -#' @param .labels character. Vector of labels to override defaults returned by -#' \code{fun} -#' @param .indent_mods integer. Named vector of indent modifiers for the -#' generated rows. -#' @param .ungroup_stats character. Vector of names, which must match elements -#' of \code{.stats} -#' @param ... dots. Additional arguments to \code{fun} which effectively become -#' new defaults. These can still be overridden by \code{extra_args} within a split. -#' @param .null_ref_cells logical(1). Should cells for the reference column be -#' NULL-ed by the returned analysis function. Defaults to \code{TRUE} if -#' \code{fun} accepts \code{.in_ref_col} as a formal argument. Note this -#' argument occurs after \code{...} so it must be \emph{fully} specified by -#' name when set. -#' @param .format_na_strs ANY. vector/list of \code{na} strings to override any -#' defaults applied by \code{fun}. -#' @return A function suitable for use in \code{\link{analyze}} with element -#' selection, reformatting, and relabeling performed automatically. -#' -#' @note setting \code{.ungroup_stats} to non-null changes the \emph{structure} -#' of the value(s) returned by \code{fun}, rather than just labeling -#' (\code{.labels}), formatting (\code{.formats}), and selecting amongst -#' (\code{.stats}) them. This means that subsequent \code{make_afun} calls to -#' customize the output further both can and must operate on the new -#' structure, \emph{NOT} the original structure returned by \code{fun}. See -#' the final pair of examples below. +#' Create a custom analysis function wrapping an existing function +#' +#' @param fun (`function`)\cr the function to be wrapped in a new customized analysis function. +#' `fun` should return a named `list`. +#' @param .stats (`character`)\cr names of elements to keep from `fun`'s full output. +#' @param .formats (`ANY`)\cr vector or list of formats to override any defaults applied by `fun`. +#' @param .labels (`character`)\cr vector of labels to override defaults returned by `fun`. +#' @param .indent_mods (`integer`)\cr named vector of indent modifiers for the generated rows. +#' @param .ungroup_stats (`character`)\cr vector of names, which must match elements of `.stats`. +#' @param ... additional arguments to `fun` which effectively become new defaults. These can still be +#' overridden by `extra_args` within a split. +#' @param .null_ref_cells (`flag`)\cr whether cells for the reference column should be `NULL`-ed by the +#' returned analysis function. Defaults to `TRUE` if `fun` accepts `.in_ref_col` as a formal argument. Note +#' this argument occurs after `...` so it must be *fully* specified by name when set. +#' @param .format_na_strs (`ANY`)\cr vector/list of `NA` strings to override any defaults applied by `fun`. +#' +#' @return A function suitable for use in [analyze()] with element selection, reformatting, and relabeling +#' performed automatically. #' -#' @seealso [analyze()] +#' @note +#' Setting `.ungroup_stats` to non-`NULL` changes the *structure* of the value(s) returned by `fun`, rather than +#' just labeling (`.labels`), formatting (`.formats`), and selecting amongst (`.stats`) them. This means that +#' subsequent `make_afun` calls to customize the output further both can and must operate on the new structure, +#' *not* the original structure returned by `fun`. See the final pair of examples below. #' -#' @export +#' @seealso [analyze()] #' #' @examples #' s_summary <- function(x) { @@ -344,8 +319,6 @@ in_rows <- function(..., .list = NULL, .names = NULL, #' #' a_summary3 <- make_afun(a_summary, .formats = c(mean_sd = "(xx.xxx, xx.xxx)")) #' -#' -#' #' s_foo <- function(df, .N_col, a = 1, b = 2) { #' list( #' nrow_df = nrow(df), @@ -411,6 +384,7 @@ in_rows <- function(..., .list = NULL, .names = NULL, #' a_ref(iris$Sepal.Length, .in_ref_col = TRUE, 1:10) #' a_ref(iris$Sepal.Length, .in_ref_col = FALSE, 1:10) #' +#' @export make_afun <- function(fun, .stats = NULL, .formats = NULL, @@ -614,7 +588,6 @@ make_afun <- function(fun, ret } - insert_replace <- function(x, nm, newvals = x[[nm]]) { i <- match(nm, names(x)) if (is.na(i)) { @@ -631,7 +604,6 @@ parser_helper <- function(text, envir = parent.frame(2)) { parse(text = text, keep.source = FALSE) } - length_w_name <- function(x, .parent_splval) { in_rows(length(x), .names = value_labels(.parent_splval) diff --git a/R/tt_compare_tables.R b/R/tt_compare_tables.R index 8ff80f12c..2ae4bb7e8 100644 --- a/R/tt_compare_tables.R +++ b/R/tt_compare_tables.R @@ -1,19 +1,15 @@ -#' Trimming and Pruning Criteria +#' Trimming and pruning criteria #' -#' Criteria functions (and constructors thereof) for trimming and pruning -#' tables. +#' Criteria functions (and constructors thereof) for trimming and pruning tables. #' #' @inheritParams gen_args #' -#' @details \code{all_zero_or_na} returns \code{TRUE} (and thus indicates -#' trimming/pruning) for any \emph{non-\code{LabelRow}} \code{TableRow} which contain -#' only any mix of \code{NA} (including \code{NaN}), \code{0}, \code{Inf} and -#' \code{-Inf} values. -#' @rdname trim_prune_funs -#' @return A logical value indicating whether \code{tr} should be included -#' (\code{TRUE}) or pruned (\code{FALSE}) during pruning. +#' @return A logical value indicating whether `tr` should be included (`TRUE`) or pruned (`FALSE`) during pruning. +#' #' @seealso [prune_table()], [trim_rows()] -#' @export +#' +#' @details `all_zero_or_na` returns `TRUE` (and thus indicates trimming/pruning) for any *non-`LabelRow`* +#' `TableRow` which contain only any mix of `NA` (including `NaN`), `0`, `Inf` and `-Inf` values. #' #' @examples #' adsl <- ex_adsl @@ -33,6 +29,8 @@ #' #' tbl_to_prune %>% prune_table(all_zero_or_na) #' +#' @rdname trim_prune_funs +#' @export all_zero_or_na <- function(tr) { if (!is(tr, "TableRow") || is(tr, "LabelRow")) { return(FALSE) @@ -41,16 +39,13 @@ all_zero_or_na <- function(tr) { all(is.na(rvs) | rvs == 0 | !is.finite(rvs)) } -#' @rdname trim_prune_funs -#' -#' @details \code{all_zero} returns \code{TRUE} for any non-Label row which -#' contains only (non-missing) zero values. -#' -#' @export +#' @details `all_zero` returns `TRUE` for any non-`LabelRow` which contains only (non-missing) zero values. #' #' @examples #' tbl_to_prune %>% prune_table(all_zero) #' +#' @rdname trim_prune_funs +#' @export all_zero <- function(tr) { if (!is(tr, "TableRow") || is(tr, "LabelRow")) { return(FALSE) @@ -58,22 +53,25 @@ all_zero <- function(tr) { rvs <- unlist(unname(row_values(tr))) isTRUE(all(rvs == 0)) } + #' Trim rows from a populated table without regard for table structure +#' #' @inheritParams gen_args -#' @param criteria function. Function which takes a `TableRow` object and returns -#' \code{TRUE} if that row should be removed. Defaults to -#' \code{\link{all_zero_or_na}} -#' @return The table with rows that have only NA or 0 cell values removed -#' @note Visible \code{LabelRow}s are including in this trimming, which can lead -#' to either all label rows being trimmed or label rows remaining when all -#' data rows have been trimmed, depending on what \code{criteria} returns when -#' called on a \code{LabelRow} object. To avoid this, use the -#' structurally-aware \code{\link{prune_table}} machinery instead. -#' @details This function will be deprecated in the future in favor of the more -#' elegant and versatile [prune_table()] function which can perform the -#' same function as `trim_rows()` but is more powerful as it takes table -#' structure into account. -#' @export +#' @param criteria (`function`)\cr function which takes a `TableRow` object and returns `TRUE` if that row +#' should be removed. Defaults to [all_zero_or_na()]. +#' +#' @return The table with rows that have only `NA` or 0 cell values removed. +#' +#' @note +#' Visible `LabelRow`s are including in this trimming, which can lead to either all label rows being trimmed or +#' label rows remaining when all data rows have been trimmed, depending on what `criteria` returns when called on +#' a `LabelRow` object. To avoid this, use the structurally-aware [prune_table()] machinery instead. +#' +#' @details +#' This function will be deprecated in the future in favor of the more elegant and versatile [prune_table()] +#' function which can perform the same function as `trim_rows()` but is more powerful as it takes table structure +#' into account. +#' #' @seealso [prune_table()] #' #' @examples @@ -94,6 +92,7 @@ all_zero <- function(tr) { #' #' tbl_to_trim %>% trim_rows(all_zero) #' +#' @export trim_rows <- function(tt, criteria = all_zero_or_na) { rows <- collect_leaves(tt, TRUE, TRUE) torm <- vapply(rows, criteria, @@ -108,21 +107,21 @@ trim_rows <- function(tt, criteria = all_zero_or_na) { ] } -#' @rdname trim_prune_funs #' @inheritParams trim_rows -#' @details \code{content_all_zeros_nas} Prunes a subtable if a) it has a -#' content table with exactly one row in it, and b) \code{all_zero_or_na} -#' returns \code{TRUE} for that single content row. In practice, when the -#' default summary/content function is used, this represents pruning any -#' subtable which corresponds to an empty set of the input data (e.g., because -#' a factor variable was used in \code{\link{split_rows_by}} but not all -#' levels were present in the data). #' -#' @export +#' @details +#' `content_all_zeros_nas` prunes a subtable if both of the following are true: +#' +#' * It has a content table with exactly one row in it. +#' * `all_zero_or_na` returns `TRUE` for that single content row. In practice, when the default summary/content +#' function is used, this represents pruning any subtable which corresponds to an empty set of the input data +#' (e.g. because a factor variable was used in [split_rows_by()] but not all levels were present in the data). #' #' @examples #' tbl_to_prune %>% prune_table(content_all_zeros_nas) #' +#' @rdname trim_prune_funs +#' @export content_all_zeros_nas <- function(tt, criteria = all_zero_or_na) { ## this will be NULL if ## tt is something that doesn't have a content table @@ -136,18 +135,16 @@ content_all_zeros_nas <- function(tt, criteria = all_zero_or_na) { criteria(cr) } - -#' @details \code{prune_empty_level} combines \code{all_zero_or_na} behavior for -#' \code{TableRow} objects, \code{content_all_zeros_nas} on -#' \code{content_table(tt)} for \code{TableTree} objects, and an additional -#' check that returns \code{TRUE} if the \code{tt} has no children. -#' -#' @export -#' @rdname trim_prune_funs +#' @details +#' `prune_empty_level` combines `all_zero_or_na` behavior for `TableRow` objects, `content_all_zeros_nas` on +#' `content_table(tt)` for `TableTree` objects, and an additional check that returns `TRUE` if the `tt` has no +#' children. #' #' @examples #' tbl_to_prune %>% prune_table(prune_empty_level) #' +#' @rdname trim_prune_funs +#' @export prune_empty_level <- function(tt) { if (is(tt, "TableRow")) { return(all_zero_or_na(tt)) @@ -160,15 +157,14 @@ prune_empty_level <- function(tt) { length(kids) == 0 } -#' @details \code{prune_zeros_only} behaves as \code{prune_empty_level} does, -#' except that like \code{all_zero} it prunes only in the case of all -#' non-missing zero values. -#' @rdname trim_prune_funs -#' @export +#' @details `prune_zeros_only` behaves as `prune_empty_level` does, except that like `all_zero` it prunes +#' only in the case of all non-missing zero values. #' #' @examples #' tbl_to_prune %>% prune_table(prune_zeros_only) #' +#' @rdname trim_prune_funs +#' @export prune_zeros_only <- function(tt) { if (is(tt, "TableRow")) { return(all_zero(tt)) @@ -181,25 +177,21 @@ prune_zeros_only <- function(tt) { length(kids) == 0 } -#' @param min numeric(1). (`low_obs_pruner` only). Minimum aggregate count value. -#' Subtables whose combined/average count are below this threshold will be -#' pruned -#' @param type character(1). How count values should be aggregated. Must be -#' \code{"sum"} (the default) or \code{"mean"} -#' -#' @details \code{low_obs_pruner} is a \emph{constructor function} which, when -#' called, returns a pruning criteria function which will prune on content -#' rows by comparing sum or mean (dictated by \code{type}) of the count -#' portions of the cell values (defined as the first value per cell regardless -#' of how many values per cell there are) against \code{min}. +#' @param min (`numeric(1)`)\cr (used by `low_obs_pruner` only). Minimum aggregate count value. +#' Subtables whose combined/average count are below this threshold will be pruned. +#' @param type (`string`)\cr how count values should be aggregated. Must be `"sum"` (the default) or `"mean"`. #' -#' @rdname trim_prune_funs -#' @export +#' @details +#' `low_obs_pruner` is a *constructor function* which, when called, returns a pruning criteria function which +#' will prune on content rows by comparing sum or mean (dictated by `type`) of the count portions of the cell +#' values (defined as the first value per cell regardless of how many values per cell there are) against `min`. #' #' @examples #' min_prune <- low_obs_pruner(70, "sum") #' tbl_to_prune %>% prune_table(min_prune) #' +#' @rdname trim_prune_funs +#' @export low_obs_pruner <- function(min, type = c("sum", "mean")) { type <- match.arg(type) function(tt) { @@ -219,20 +211,16 @@ low_obs_pruner <- function(min, type = c("sum", "mean")) { #' Recursively prune a `TableTree` #' #' @inheritParams gen_args -#' @param prune_func function. A Function to be called on each subtree which -#' returns TRUE if the entire subtree should be removed. -#' @param stop_depth numeric(1). The depth after which subtrees should not be -#' checked for pruning. Defaults to \code{NA} which indicates pruning should -#' happen at all levels -#' @param depth numeric(1). Used internally, not intended to be set by the end -#' user. +#' @param prune_func (`function`)\cr a function to be called on each subtree which returns `TRUE` if the +#' entire subtree should be removed. +#' @param stop_depth (`numeric(1)`)\cr the depth after which subtrees should not be checked for pruning. +#' Defaults to `NA` which indicates pruning should happen at all levels. +#' @param depth (`numeric(1)`)\cr used internally, not intended to be set by the end user. #' -#' @return A `TableTree` pruned via recursive application of \code{prune_func}. +#' @return A `TableTree` pruned via recursive application of `prune_func`. #' -#' @export -#' -#' @seealso [prune_empty_level()] for details on this and several other basic -#' pruning functions included in the `rtables` package. +#' @seealso [prune_empty_level()] for details on this and several other basic pruning functions included +#' in the `rtables` package. #' #' @examples #' adsl <- ex_adsl @@ -249,6 +237,7 @@ low_obs_pruner <- function(min, type = c("sum", "mean")) { #' #' tbl_to_prune %>% prune_table() #' +#' @export prune_table <- function(tt, prune_func = prune_empty_level, stop_depth = NA_real_, diff --git a/R/tt_compatibility.R b/R/tt_compatibility.R index 529b596b9..35e42dab1 100644 --- a/R/tt_compatibility.R +++ b/R/tt_compatibility.R @@ -1,15 +1,16 @@ -#' row +#' Create an `rtable` row #' #' @inheritParams compat_args -#' @param \dots cell values +#' @param ... cell values. +#' +#' @return A row object of the context-appropriate type (label or data). #' -#' @export -#' @return A row object of the context-appropriate type (label or data) -#' @family compatibility #' @examples #' rrow("ABC", c(1, 2), c(3, 2), format = "xx (xx.%)") #' rrow("") #' +#' @family compatibility +#' @export rrow <- function(row.name = "", ..., format = NULL, indent = 0, inset = 0L) { vals <- list(...) if (is.null(row.name)) { @@ -45,15 +46,13 @@ rrow <- function(row.name = "", ..., format = NULL, indent = 0, inset = 0L) { } } - -#' `rrowl` +#' Create an `rtable` row from a vector or list of values #' #' @inheritParams compat_args -#' @param \dots values in vector/list form +#' @param ... values in vector/list form. #' #' @inherit rrow return -#' @export -#' @family compatibility +#' #' @examples #' rrowl("a", c(1, 2, 3), format = "xx") #' rrowl("a", c(1, 2, 3), c(4, 5, 6), format = "xx") @@ -69,6 +68,9 @@ rrow <- function(row.name = "", ..., format = NULL, indent = 0, inset = 0L) { #' #' rrowl(row.name = "row 1", c(1, 2), c(3, 4)) #' rrow(row.name = "row 2", c(1, 2), c(3, 4)) +#' +#' @family compatibility +#' @export rrowl <- function(row.name, ..., format = NULL, indent = 0, inset = 0L) { dots <- list(...) args_list <- c(list( @@ -91,7 +93,6 @@ paste_em_n <- function(lst, n, sep = ".") { ret } - hrows_to_colinfo <- function(rows) { nr <- length(rows) stopifnot(nr > 0) @@ -151,40 +152,35 @@ hrows_to_colinfo <- function(rows) { ## we will build it up as if it were full nesting and then prune ## based on the columns we actually want. - fullcolinfo <- manual_cols(.lst = unqvals) fullbusiness <- names(collect_leaves(coltree(fullcolinfo))) wanted <- paste_em_n(repvals, nr) wantcols <- match(wanted, fullbusiness) stopifnot(all(!is.na(wantcols))) - subset_cols(fullcolinfo, wantcols) } - #' Create a header #' #' @inheritParams compat_args -#' @param \dots row specifications (either as character vectors or the output -#' from \code{\link{rrow}} or \code{\link{DataRow}}, \code{\link{LabelRow}}, -#' etc. +#' @param ... row specifications, either as character vectors or the output from [rrow()], [DataRow()], +#' [LabelRow()], etc. +#' +#' @return A `InstantiatedColumnInfo` object. #' -#' @export -#' @return a \code{InstantiatedColumnInfo} object. -#' @family compatibility #' @examples #' h1 <- rheader(c("A", "B", "C")) +#' h1 #' #' h2 <- rheader( #' rrow(NULL, rcell("group 1", colspan = 2), rcell("group 2", colspan = 2)), #' rrow(NULL, "A", "B", "A", "B") #' ) -#' -#' h1 -#' #' h2 #' +#' @family compatibility +#' @export rheader <- function(..., format = "xx", .lst = NULL) { if (!is.null(.lst)) { args <- .lst @@ -200,7 +196,6 @@ rheader <- function(..., format = "xx", .lst = NULL) { hrows_to_colinfo(rrows) } - .char_to_hrows <- function(hdr) { nlfnd <- grep("\n", hdr, fixed = TRUE) if (length(nlfnd) == 0) { @@ -219,23 +214,17 @@ rheader <- function(..., format = "xx", .lst = NULL) { ) } - -#' Create a Table -#' -#' @rdname rtable +#' Create a table #' #' @inheritParams compat_args #' @inheritParams gen_args -#' @param header Information defining the header (column structure) of the table. -#' This can be as row objects (legacy), character vectors or a -#' \code{InstantiatedColumnInfo} object. -#' @param \dots Rows to place in the table. +#' @param header (`TableRow`, `character`, or `InstantiatedColumnInfo`)\cr information defining the header +#' (column structure) of the table. This can be as row objects (legacy), character vectors, or an +#' `InstantiatedColumnInfo` object. +#' @param ... rows to place in the table. #' +#' @return A formal table object of the appropriate type (`ElementaryTable` or `TableTree`). #' -#' @export -#' @return a formal table object of the appropriate type (\code{ElementaryTable} -#' or \code{TableTree}) -#' @family compatibility #' @examples #' rtable( #' header = LETTERS[1:3], @@ -243,8 +232,8 @@ rheader <- function(..., format = "xx", .lst = NULL) { #' rrow("more stuff", rcell(pi, format = "xx.xx"), "test", "and more") #' ) #' -#' #' # Table with multirow header +#' #' sel <- iris$Species == "setosa" #' mtbl <- rtable( #' header = rheader( @@ -288,8 +277,8 @@ rheader <- function(..., format = "xx", .lst = NULL) { #' row.names(tbl) #' names(tbl) #' -#' #' # Subsetting +#' #' tbl[1, ] #' tbl[, 1] #' @@ -300,13 +289,13 @@ rheader <- function(..., format = "xx", .lst = NULL) { #' tbl[5, 1] #' tbl[5, 2] #' -#' # # Data Structure methods +#' # Data Structure methods +#' #' dim(tbl) #' nrow(tbl) #' ncol(tbl) #' names(tbl) #' -#' #' # Colspans #' #' tbl2 <- rtable( @@ -315,9 +304,10 @@ rheader <- function(..., format = "xx", .lst = NULL) { #' rrow("r1", 1, 2, 3, 4, 5), #' rrow("r2", rcell("sp2", colspan = 2), "sp1", rcell("sp2-2", colspan = 2)) #' ) -#' #' tbl2 #' +#' @family compatibility +#' @export rtable <- function(header, ..., format = NULL, hsep = default_hsep(), inset = 0L) { if (is.character(header)) { @@ -385,11 +375,14 @@ only_first_annot <- function(all_annots) { } } -#' @rdname rbind +#' @param gap `r lifecycle::badge("deprecated")` ignored. +#' @param check_headers `r lifecycle::badge("deprecated")` ignored. +#' #' @return A formal table object. +#' +#' @rdname rbind +#' @aliases rbind #' @export -#' @param gap deprecated. Ignored. -#' @param check_headers deprecated. Ignored. rbindl_rtables <- function(x, gap = 0, check_headers = TRUE) { if (!check_headers) { warning("check_headers = FALSE is no longer supported, ignoring.") @@ -455,7 +448,6 @@ rbindl_rtables <- function(x, gap = 0, check_headers = TRUE) { })) } - TableTree( kids = x, cinfo = firstcols, @@ -468,12 +460,10 @@ rbindl_rtables <- function(x, gap = 0, check_headers = TRUE) { ) } -#' `rbind` `TableTree` and related objects -#' @rdname rbind -#' @aliases rbind -#' @exportMethod rbind -#' @param deparse.level numeric(1). Currently Ignored. -#' @param \dots ANY. Elements to be stacked. +#' Row-bind `TableTree` and related objects +#' +#' @param deparse.level (`numeric(1)`)\cr currently ignored. +#' @param ... (`ANY`)\cr elements to be stacked. #' #' @note #' When objects are row-bound, titles and footer information is retained from the first object (if any exists) if all @@ -511,6 +501,9 @@ rbindl_rtables <- function(x, gap = 0, check_headers = TRUE) { #' rbind(mtbl, mtbl2) #' rbind(mtbl, rrow(), mtbl2) #' rbind(mtbl, rrow("aaa"), indent(mtbl2)) +#' +#' @exportMethod rbind +#' @rdname rbind setMethod( "rbind", "VTableNodeInfo", function(..., deparse.level = 1) { @@ -518,8 +511,9 @@ setMethod( } ) +#' @param y (`ANY`)\cr second element to be row-bound via `rbind2`. +#' #' @exportMethod rbind2 -#' @param y Second element to be `rbound` via `rbind2` #' @rdname int_methods setMethod( "rbind2", c("VTableNodeInfo", "missing"), @@ -528,9 +522,10 @@ setMethod( } ) +#' @param x (`VTableNodeInfo`)\cr `TableTree`, `ElementaryTable`, or `TableRow` object. +#' @param y (`VTableNodeInfo`)\cr `TableTree`, `ElementaryTable`, or `TableRow` object. +#' #' @exportMethod rbind2 -#' @param x `VTableNodeInfo`. `TableTree`, `ElementaryTable` or `TableRow` object. -#' @param y `VTableNodeInfo`. `TableTree`, `ElementaryTable` or `TableRow` object. #' @rdname rbind setMethod( "rbind2", "VTableNodeInfo", @@ -539,8 +534,6 @@ setMethod( } ) - - combine_cinfo <- function(..., new_total = NULL) { tabs <- list(...) chk_cbindable_many(tabs) @@ -586,11 +579,11 @@ nz_len_els <- function(lst) { lst } } + has_one_unq <- function(x) { length(unique(nz_len_els(x))) <= 1 } - classvec <- function(lst, enforce_one = TRUE) { if (enforce_one) { vapply(lst, class, "") @@ -656,19 +649,16 @@ chk_cbindable_many <- function(lst) { TRUE } - -#' `cbind` two `rtables` +#' Column-bind two `TableTree` objects +#' +#' @param x (`TableTree` or `TableRow`)\cr a table or row object. +#' @param ... one or more further objects of the same class as `x`. #' -#' @param x A table or row object -#' @param \dots 1 or more further objects of the same class as \code{x} #' @inherit rbindl_rtables return -#' @export #' #' @examples #' x <- rtable(c("A", "B"), rrow("row 1", 1, 2), rrow("row 2", 3, 4)) -#' #' y <- rtable("C", rrow("row 1", 5), rrow("row 2", 6)) -#' #' z <- rtable("D", rrow("row 1", 9), rrow("row 2", 10)) #' #' t1 <- cbind_rtables(x, y) @@ -680,6 +670,7 @@ chk_cbindable_many <- function(lst) { #' col_paths_summary(t1) #' col_paths_summary(t2) #' +#' @export cbind_rtables <- function(x, ...) { lst <- list(...) newcinfo <- combine_cinfo(x, ...) @@ -776,7 +767,6 @@ setMethod( ) names(kids) <- names(tree_children(x)) - ElementaryTable( kids = kids, labelrow = recurse_cbindl(tt_labelrow(x), @@ -792,9 +782,6 @@ setMethod( } ) - - - .combine_rows <- function(x, cinfo = NULL, .list) { stopifnot(are(.list, class(x))) @@ -805,7 +792,6 @@ setMethod( stop("Got rows that don't analyze the same variable") } - xlst <- c(list(x), .list) ncols <- vapply(xlst, ncol, 1L) @@ -859,6 +845,7 @@ setMethod( label = obj_label(x) ) } + setMethod( "recurse_cbindl", c( "TableRow", @@ -880,8 +867,6 @@ setMethod( } ) - - ## we don't care about the following discrepencies: ## - ci2 having NA counts when ci1 doesn't ## - mismatching display_ccounts values @@ -941,25 +926,22 @@ chk_compat_cinfos <- function(tt1, tt2) { } -#' \[DEPRECATED\] insert `rrows` at (before) a specific location +#' **Deprecated:** Insert `rrow`s at (before) a specific location #' -#' This function is deprecated and will be removed in a future release of -#' `rtables`. Please use \code{\link{insert_row_at_path}} or -#' \code{\link{label_at_path}} instead. -#' @param tbl `rtable` -#' @param rrow `rrow` to append to `rtable` -#' @param at position into which to put the `rrow`, defaults to beginning (i.e. 1) -#' @param ascontent logical. Currently ignored. +#' This function is deprecated and will be removed in a future release of `rtables`. Please use +#' [insert_row_at_path()] or [label_at_path()] instead. #' -#' @return A `TableTree` of the same specific class as \code{tbl} +#' @param tbl (`VTableTree`)\cr a `rtable` object. +#' @param rrow (`TableRow`)\cr an `rrow` to append to `tbl`. +#' @param at (`integer(1)`)\cr position into which to put the `rrow`, defaults to beginning (i.e. row 1). +#' @param ascontent (`flag`)\cr currently ignored. #' -#' @export +#' @return A `TableTree` of the same specific class as `tbl`. #' -#' @inherit rbindl_rtables return +#' @note +#' Label rows (i.e. a row with no data values, only a `row.name`) can only be inserted at positions which do +#' not already contain a label row when there is a non-trivial nested row structure in `tbl`. #' -#' @note Label rows (i.e. a row with no data values, only a `row.name`) can only be -#' inserted at positions which do not already contain a label row when there -#' is a non-trivial nested row structure in \code{tbl} #' @examples #' o <- options(warn = 0) #' lyt <- basic_table() %>% @@ -987,6 +969,8 @@ chk_compat_cinfos <- function(tt1, tt2) { #' insert_rrow(tbl2, rrow("new row", 5, 6, 7), at = 3) #' #' options(o) +#' +#' @export insert_rrow <- function(tbl, rrow, at = 1, ascontent = FALSE) { .Deprecated("insert_row_at_path or label_at_path(tab)<-", old = "insert_rrow") @@ -1016,7 +1000,6 @@ insert_rrow <- function(tbl, rrow, at = 1, ret } - .insert_helper <- function(tt, row, at, pos, ascontent = FALSE) { islab <- is(row, "LabelRow") @@ -1031,7 +1014,6 @@ insert_rrow <- function(tbl, rrow, at = 1, } contnr <- contnr + as.numeric(labelrow_visible(tt)) - totnr <- nrow(tt) endpos <- pos + totnr atend <- !islab && endpos == at - 1 @@ -1061,7 +1043,6 @@ insert_rrow <- function(tbl, rrow, at = 1, kidnrs <- sapply(kids, nrow) cumpos <- pos + cumsum(kidnrs) - ## data rows go in the end of the ## preceding subtable (if applicable) ## label rows go in the beginning of @@ -1107,8 +1088,8 @@ insert_rrow <- function(tbl, rrow, at = 1, tt } - setGeneric("recurse_insert", function(tt, row, at, pos, ascontent = FALSE) standardGeneric("recurse_insert")) + setMethod( "recurse_insert", "TableTree", function(tt, row, at, pos, ascontent = FALSE) { diff --git a/R/tt_dotabulation.R b/R/tt_dotabulation.R index cdafe5b7d..791b0a9ae 100644 --- a/R/tt_dotabulation.R +++ b/R/tt_dotabulation.R @@ -67,9 +67,9 @@ match_extra_args <- function(f, } #' @noRd -#' @return a RowsVerticalSection object representing the k x 1 section of the -#' table being generated, with k the number of rows the analysis function -#' generates +#' @return A `RowsVerticalSection` object representing the `k x 1` section of the +#' table being generated, with `k` the number of rows the analysis function +#' generates. gen_onerv <- function(csub, col, count, cextr, cpath, dfpart, func, totcount, splextra, all_col_exprs, @@ -156,7 +156,6 @@ gen_onerv <- function(csub, col, count, cextr, cpath, args <- c(args, exargs) - val <- do.call(func, args) if (!is(val, "RowsVerticalSection")) { if (!is(val, "list")) { @@ -173,17 +172,14 @@ gen_onerv <- function(csub, col, count, cextr, cpath, ret } - strip_multivar_suffix <- function(x) { gsub("\\._\\[\\[[0-9]\\]\\]_\\.$", "", x) } - ## Generate all values (one for each column) for one or more rows ## by calling func once per column (as defined by cinfo) #' @noRd -#' @return A list of m RowsVerticalSection objects, one for each -#' (leaf) column in the table. +#' @return A list of `m` `RowsVerticalSection` objects, one for each (leaf) column in the table. gen_rowvalues <- function(dfpart, datcol, cinfo, @@ -204,7 +200,6 @@ gen_rowvalues <- function(dfpart, colleaves <- collect_leaves(cinfo@tree_layout) - gotflist <- is.list(func) ## one set of named args to be applied to all columns @@ -214,7 +209,6 @@ gen_rowvalues <- function(dfpart, length(splextra) <- ncol(cinfo) } - if (!gotflist) { func <- list(func) } else if (length(splextra) == 1) { @@ -299,19 +293,16 @@ gen_rowvalues <- function(dfpart, SIMPLIFY = FALSE ) - names(rawvals) <- names(colexprs) rawvals } - - .strip_lst_rvals <- function(lst) { lapply(lst, rawvalues) } #' @noRd -#' @return a list of table rows, even when only one is generated +#' @return A list of table rows, even when only one is generated. .make_tablerows <- function(dfpart, alt_dfpart, func, @@ -423,8 +414,6 @@ gen_rowvalues <- function(dfpart, formatvec <- rep(format, length.out = ncrows) } - - trows <- lapply(1:ncrows, function(i) { rowvals <- lapply(unwrapped_vals, function(colvals) { colvals[[i]] @@ -547,7 +536,6 @@ gen_rowvalues <- function(dfpart, ctab } - .make_analyzed_tab <- function(df, alt_df, spl, @@ -607,11 +595,10 @@ gen_rowvalues <- function(dfpart, ret } -#' @noRd -#' @param \dots ALL arguments to recurse_applysplit, methods may only use some -#' of them. -#' @return list of children to place at this level +#' @param ... all arguments to `recurse_applysplit`, methods may only use some of them. +#' @return A `list` of children to place at this level. #' +#' @noRd setGeneric(".make_split_kids", function(spl, have_controws, make_lrow, ...) { standardGeneric(".make_split_kids") }) @@ -733,7 +720,6 @@ setMethod( } ) - setMethod( ".make_split_kids", "Split", function(spl, @@ -761,7 +747,6 @@ setMethod( nms <- as.character(nms) } - ## ## Get new baseline values ## ## XXX this is a lot of data churn, if it proves too slow @@ -1005,7 +990,6 @@ context_df_row <- function(split = character(), ret } - recursive_applysplit <- function(df, lvl = 0L, alt_df, @@ -1141,44 +1125,35 @@ recursive_applysplit <- function(df, ret } - - #' Create a table from a layout and data #' -#' Layouts are used to describe a table pre-data. `build_table` is used to -#' create a table using a layout and a dataset. +#' Layouts are used to describe a table pre-data. `build_table` is used to create a table +#' using a layout and a dataset. #' #' @inheritParams gen_args #' @inheritParams lyt_args -#' @param col_counts numeric (or `NULL`). Deprecated. If non-null, column counts -#' which override those calculated automatically during tabulation. Must -#' specify "counts" for \emph{all} resulting columns if non-NULL. \code{NA} -#' elements will be replaced with the automatically calculated counts. -#' @param col_total integer(1). The total observations across all columns. -#' Defaults to \code{nrow(df)}. -#' @param \dots currently ignored. +#' @param col_counts (`numeric` or `NULL`)\cr `r lifecycle::badge("deprecated")` if non-`NULL`, column counts +#' which override those calculated automatically during tabulation. Must specify "counts" for *all* +#' resulting columns if non-`NULL`. `NA` elements will be replaced with the automatically calculated counts. +#' @param col_total (`integer(1)`)\cr the total observations across all columns. Defaults to `nrow(df)`. +#' @param ... ignored. #' #' @details -#' When \code{alt_counts_df} is specified, column counts are calculated by -#' applying the exact column subsetting expressions determined when applying -#' column splitting to the main data (\code{df}) to \code{alt_counts_df} and +#' When `alt_counts_df` is specified, column counts are calculated by applying the exact column subsetting +#' expressions determined when applying column splitting to the main data (`df`) to `alt_counts_df` and #' counting the observations in each resulting subset. #' -#' In particular, this means that in the case of splitting based on cuts of the -#' data, any dynamic cuts will have been calculated based on \code{df} and -#' simply re-used for the count calculation. +#' In particular, this means that in the case of splitting based on cuts of the data, any dynamic cuts will have +#' been calculated based on `df` and simply re-used for the count calculation. #' -#' @note When overriding the column counts or totals care must be taken that, -#' e.g., `length()` or `nrow()` are not called within tabulation functions, -#' because those will NOT give the overridden counts. Writing/using tabulation -#' functions which accept \code{.N_col} and \code{.N_total} or do not rely on -#' column counts at all (even implicitly) is the only way to ensure overridden -#' counts are fully respected. +#' @note +#' When overriding the column counts or totals care must be taken that, e.g., `length()` or `nrow()` are not called +#' within tabulation functions, because those will NOT give the overridden counts. Writing/using tabulation +#' functions which accept `.N_col` and `.N_total` or do not rely on column counts at all (even implicitly) is the +#' only way to ensure overridden counts are fully respected. #' -#' @return A \code{TableTree} or \code{ElementaryTable} object representing the -#' table created by performing the tabulations declared in \code{lyt} to the -#' data \code{df}. -#' @author Gabriel Becker +#' @return A `TableTree` or `ElementaryTable` object representing the table created by performing the tabulations +#' declared in `lyt` to the data `df`. #' #' @examples #' lyt <- basic_table() %>% @@ -1189,7 +1164,6 @@ recursive_applysplit <- function(df, #' "range" = diff(range(x)) #' ) #' }) -#' #' lyt #' #' tbl <- build_table(lyt, iris) @@ -1232,6 +1206,7 @@ recursive_applysplit <- function(df, #' tbl6 <- build_table(lyt3, DM, col_counts = 1:3) #' tbl6 #' +#' @author Gabriel Becker #' @export build_table <- function(lyt, df, alt_counts_df = NULL, @@ -1366,12 +1341,10 @@ build_table <- function(lyt, df, ) } - ## This seems to be unneeded, not clear what 'top_left' check it refers to ## but both top_left taller than column headers and very long topleft are now ## allowed, so this is just wasted computation. - ## ## this is where the top_left check lives right now. refactor later maybe ## ## but now just call it so the error gets thrown when I want it to ## unused <- matrix_form(tab) @@ -1576,7 +1549,6 @@ setMethod( } ) - splitvec_to_coltree <- function(df, splvec, pos = NULL, lvl = 1L, label = "", spl_context = context_df_row(cinfo = NULL)) { @@ -1648,6 +1620,7 @@ splitvec_to_coltree <- function(df, splvec, pos = NULL, ## labelrows should be visible for ElementaryTables ## generatead from analyzing a single variable setGeneric("fix_analyze_vis", function(lyt) standardGeneric("fix_analyze_vis")) + setMethod( "fix_analyze_vis", "PreDataTableLayouts", function(lyt) { @@ -1655,6 +1628,7 @@ setMethod( lyt } ) + setMethod( "fix_analyze_vis", "PreDataRowLayout", function(lyt) { @@ -1700,6 +1674,7 @@ setMethod( ) # check_afun_cfun_params ---- + # This checks if the input params are used anywhere in cfun/afun setGeneric("check_afun_cfun_params", function(lyt, params) { standardGeneric("check_afun_cfun_params") @@ -1759,7 +1734,8 @@ setMethod( } ) -# Helper fnc ---- +# Helper functions ---- + count <- function(df, ...) NROW(df) guess_format <- function(val) { @@ -1842,58 +1818,49 @@ n_cells_res <- function(res) { ans } -#' Generalized Frequency Table +#' Generalized frequency table #' -#' @description This function provides a convenience interface for -#' generating generalizations of a 2-way frequency table. Row and column -#' space can be facetted by variables, and an analysis function can be specified. +#' This function provides a convenience interface for generating generalizations of a 2-way frequency table. Row and +#' column space can be facetted by variables, and an analysis function can be specified. The function then builds a +#' layout with the specified layout and applies it to the data provided. #' -#' The function then builds a layout with the specified layout and applies it to -#' the data provided. -#' -#' @param row_vars character. The names of variables to be used in row facetting. -#' @param col_vars character. The names of variables to be used in column facetting. -#' @param data data.frame. The data to tabulate. -#' @param avar character(1). The variable to be analyzed. Defaults to the first variable in `data`. -#' @param row_labels character or NULL. Row label(s) which should be applied to the analysis rows. length must match -#' the number of rows generated by `afun`. See details. -#' @param afun function. The function to generate the analysis row cell values. This can be a proper analysis -#' function, or a function which returns a vector or list. Vectors are taken as multi-valued single cells, whereas -#' lists are interpreted as multiple cells. -#' @param drop_levels logical(1). Should unobserved factor levels be dropped during facetting. Defaults to `TRUE`. -#' @param summarize_groups logical(1). Should each level of nesting include marginal summary rows. Defaults to `FALSE` -#' @param ... passed to `afun`, if specified. Otherwise ignored. -#' @param .default_rlabel character(1). This is an implementation detail that should not be set by end users. #' @inheritParams constr_args #' @inheritParams basic_table +#' @param row_vars (`character`)\cr the names of variables to be used in row facetting. +#' @param col_vars (`character`)\cr the names of variables to be used in column facetting. +#' @param data (`data.frame`)\cr the data to tabulate. +#' @param avar (`string`)\cr the variable to be analyzed. Defaults to the first variable in `data`. +#' @param row_labels (`character` or `NULL`)\cr row label(s) which should be applied to the analysis rows. Length must +#' match the number of rows generated by `afun`. +#' @param afun (`function`)\cr the function to generate the analysis row cell values. This can be a proper analysis +#' function, or a function which returns a vector or list. Vectors are taken as multi-valued single cells, whereas +#' lists are interpreted as multiple cells. +#' @param drop_levels (`flag`)\cr whether unobserved factor levels should be dropped during facetting. Defaults to +#' `TRUE`. +#' @param summarize_groups (`flag`)\cr whether each level of nesting should include marginal summary rows. Defaults to +#' `FALSE`. +#' @param ... additional arguments passed to `afun`. +#' @param .default_rlabel (`string`)\cr this is an implementation detail that should not be set by end users. #' #' @details +#' This function creates a table with a single top-level structure in both row and column dimensions involving faceting +#' by 0 or more variables in each dimension. #' -#' This function creates a table with a single top-level structure in -#' both row and column dimensions involving faceting by 0 or more -#' variables in each. +#' The display of the table depends on certain details of the tabulation. In the case of an `afun` which returns a +#' single cell's contents (either a scalar or a vector of 2 or 3 elements), the label rows for the deepest-nested row +#' facets will be hidden and the labels used there will be used as the analysis row labels. In the case of an `afun` +#' which returns a list (corresponding to multiple cells), the names of the list will be used as the analysis row +#' labels and the deepest-nested facet row labels will be visible. #' -#' The display of the table depends on certain -#' details of the tabulation. In the case of an `afun` which -#' returns a single cell's contents (either a scalar or a vector -#' of 2 or 3 elements), the label rows for the deepest-nested row -#' facets will be hidden and the labels used there will be used as -#' the analysis row labels. In the case of an `afun` which returns a -#' list (corresponding to multiple cells), the names of the list -#' will be used as the analysis row labels and the deepest-nested -#' facet row labels will be visible. +#' The table will be annotated in the top-left area with an informative label displaying the analysis variable +#' (`avar`), if set, and the function used (captured via substitute) where possible, or 'count' if not. One exception +#' where the user may directly modify the top-left area (via `row_labels`) is the case of a table with row facets and +#' an `afun` which returns a single row. #' -#' The table will be annotated in the top-left area with an -#' informative label displaying the analysis variable (`avar`), if -#' set, and the function used (captured via substitute) where -#' possible, or 'count' if not. One exception where the user may -#' directly modify the top-left area (via `row_labels`) is the case of -#' a table with row facets and an `afun` which returns a single row. -#' -#' -#' @return for `qtable` a built TableTree object representing the desired table, -#' for `qtable_layout`, a `PreDataTableLayouts` object declaring the structure of -#' the desired table, suitable for passing to `build_table`. +#' @return +#' * `qtable` returns a built `TableTree` object representing the desired table +#' * `qtable_layout` returns a `PreDataTableLayouts` object declaring the structure of the desired table, suitable for +#' passing to [build_table()]. #' #' @examples #' qtable(ex_adsl) @@ -1911,6 +1878,7 @@ n_cells_res <- function(res) { #' row_vars = "SEX", #' col_vars = "ARM", avar = "AGE", afun = range #' )) +#' #' @export qtable_layout <- function(data, row_vars = character(), @@ -1978,7 +1946,6 @@ qtable_layout <- function(data, row_labels <- dflt_row_lbl } - lyt <- basic_table( title = title, subtitles = subtitles, diff --git a/R/tt_export.R b/R/tt_export.R index c85b6248e..6583f73cc 100644 --- a/R/tt_export.R +++ b/R/tt_export.R @@ -1,38 +1,37 @@ #' @importFrom tools file_ext NULL -#' Create Enriched flat value table with paths +#' Create enriched flat value table with paths #' -#' @description -#' This function creates a flat tabular file of cell values and -#' corresponding paths via [path_enriched_df()]. I then -#' writes that data.frame out as a `tsv` file. +#' This function creates a flat tabular file of cell values and corresponding paths via [path_enriched_df()]. It then +#' writes that data frame out as a `tsv` file. #' -#' By default (i.e. when \code{value_func} is not specified, -#' List columns where at least one value has length > 1 are collapsed -#' to character vectors by collapsing the list element with \code{"|"}. +#' By default (i.e. when `value_func` is not specified, list columns where at least one value has length > 1 are +#' collapsed to character vectors by collapsing the list element with `"|"`. #' -#' @note There is currently no round-trip capability for this type of export. -#' You can read values exported this way back in via \code{import_from_tsv} -#' but you will receive only the data.frame version back, NOT a \code{TableTree}. +#' @note +#' There is currently no round-trip capability for this type of export. You can read values exported this way back in +#' via `import_from_tsv` but you will receive only the `data.frame` version back, NOT a `TableTree`. #' #' @inheritParams gen_args -#' @param file character(1). The path of the file to written to or read from. #' @inheritParams data.frame_export +#' @param file (`string`)\cr the path of the file to written to or read from. #' -#' @return \code{NULL} silently for \code{export_as_tsv}, a data.frame with -#' re-constituted list values for \code{export_as_tsv}. +#' @return +#' * `export_as_tsv` returns `NULL` silently. +#' * `import_from_tsv` returns a `data.frame` with re-constituted list values. #' #' @seealso [path_enriched_df()] for the underlying function that does the work. #' -#' @rdname tsv_io #' @importFrom utils write.table read.table +#' @rdname tsv_io #' @export export_as_tsv <- function(tt, file = NULL, path_fun = collapse_path, value_fun = collapse_values) { df <- path_enriched_df(tt, path_fun = path_fun, value_fun = value_fun) write.table(df, file, sep = "\t") } + #' @rdname tsv_io #' @export import_from_tsv <- function(file) { @@ -49,7 +48,7 @@ import_from_tsv <- function(file) { )) } -### Migrated to formatters. +### Migrated to formatters ---- #' @importFrom formatters export_as_txt #' @@ -67,23 +66,21 @@ import_from_tsv <- function(file) { #' export_as_txt(tbl, file = tf) #' system2("cat", tf) #' } +#' #' @export formatters::export_as_txt # data.frame output ------------------------------------------------------------ -#' Generate a Result Data Frame +#' Generate a result data frame #' -#' @description -#' Collection of utilities to extract `data.frame` from `TableTree` objects. +#' Collection of utilities to extract `data.frame` objects from `TableTree` objects. #' #' @inheritParams gen_args -#' @param spec character(1). The specification to use to -#' extract the result data frame. See details -#' @param simplify logical(1). If \code{TRUE}, the result data frame will have only visible -#' labels and result columns. -#' @param ... Passed to spec-specific result data frame conversion function. Currently it can be -#' one or more of the following parameters (valid only for `v0_experimental` spec for now): +#' @param spec (`string`)\cr the specification to use to extract the result data frame. See Details below. +#' @param simplify (`flag`)\cr whether the result data frame should only have labels and result columns visible. +#' @param ... additional arguments passed to spec-specific result data frame conversion function. Currently it can be +#' one or more of the following parameters (valid only for `v0_experimental` spec. for now): #' - `expand_colnames`: when `TRUE`, the result data frame will have expanded column names above the usual #' output. This is useful when the result data frame is used for further processing. #' - `simplify`: when `TRUE`, the result data frame will have only visible labels and result columns. @@ -101,7 +98,10 @@ formatters::export_as_txt #' @details `as_result_df()`: Result data frame specifications may differ in the exact information #' they include and the form in which they represent it. Specifications whose names end in "_experimental" #' are subject to change without notice, but specifications without the "_experimental" -#' suffix will remain available \emph{including any bugs in their construction} indefinitely. +#' suffix will remain available *including any bugs in their construction* indefinitely. +#' +#' @return +#' * `as_result_df` returns a result `data.frame`. #' #' @seealso [df_to_tt()] when using `as_is = TRUE` and [make_row_df()] to have a comprehensive view of the #' hierarchical structure of the rows. @@ -163,9 +163,10 @@ as_result_df <- function(tt, spec = "v0_experimental", simplify = FALSE, ...) { # ret # } -#' @describeIn data.frame_export list of functions that extract result data frames from \code{TableTree}s. +#' @describeIn data.frame_export A list of functions that extract result data frames from `TableTree`s. #' -#' @return `result_df_specs()`: returns a named list of result data frame extraction functions by "specification". +#' @return +#' * `result_df_specs()` returns a named list of result data frame extraction functions by "specification". #' #' @examples #' result_df_specs() @@ -479,18 +480,16 @@ handle_rdf_row <- function(rdfrow, maxlen) { } } -#' @describeIn data.frame_export transform `TableTree` object to Path-Enriched `data.frame`. +#' @describeIn data.frame_export Transform a `TableTree` object to a path-enriched `data.frame`. #' -#' @param path_fun function. Function to transform paths into single-string -#' row/column names. -#' @param value_fun function. Function to transform cell values into cells of -#' the data.frame. Defaults to \code{collapse_values} which creates strings -#' where multi-valued cells are collapsed together, separated by \code{|}. +#' @param path_fun (`function`)\cr function to transform paths into single-string row/column names. +#' @param value_fun (`function`)\cr function to transform cell values into cells of a `data.frame`. Defaults to +#' `collapse_values`, which creates strings where multi-valued cells are collapsed together, separated by `|`. #' -#' @return `path_enriched_df()`: returns a data frame of \code{tt}'s cell values (processed by -#' \code{value_fun}, with columns named by the full column paths (processed by -#' \code{path_fun} and an additional \code{row_path} column with the row paths -#' (processed by by \code{path_fun}). +#' @return +#' * `path_enriched_df()` returns a `data.frame` of `tt`'s cell values (processed by `value_fun`, with columns named by +#' the full column paths (processed by `path_fun` and an additional `row_path` column with the row paths (processed +#' by `path_fun`). #' #' @examples #' lyt <- basic_table() %>% @@ -531,11 +530,9 @@ collapse_values <- function(colvals) { vapply(colvals, paste, "", collapse = .collapse_char) } - # pdf output ------------------------------------------------------------------- -#' Export as PDF -### Migrated to formatters. +### Export as PDF - migrated to formatters #' @importFrom formatters export_as_pdf #' @@ -552,6 +549,7 @@ collapse_values <- function(colvals) { #' tf <- tempfile(fileext = ".pdf") #' export_as_pdf(tbl, file = tf, lpp = 8) #' } +#' #' @export formatters::export_as_pdf @@ -569,31 +567,29 @@ formatters::export_as_pdf .tab_to_colpath_set(fulltab) ) } + # Flextable and docx ----------------------------------------------------------- + #' Export as word document #' -#' @description #' From a table, produce a self-contained word document or attach it to a template word -#' file (`template_file`). This function is based on [tt_to_flextable()] transformer and -#' `officer` package. +#' file (`template_file`). This function is based on the [tt_to_flextable()] transformer and +#' the `officer` package. #' #' @inheritParams gen_args -#' @param file character(1). String that indicates the final file output. It needs to have `.docx` -#' extension. -#' @param doc_metadata list of character(1)s. Any value that can be used as metadata by -#' `?officer::set_doc_properties`. Important text values are `title, subject, creator, description` +#' @param file (`string`)\cr string that indicates the final file output. Must have `.docx` extension. +#' @param doc_metadata (`list` of `string`s)\cr any value that can be used as metadata by +#' `?officer::set_doc_properties`. Important text values are `title`, `subject`, `creator`, and `description`, #' while `created` is a date object. #' @inheritParams tt_to_flextable -#' @param template_file character(1). Template file that `officer` will use as a starting -#' point for the final document. It will attach the table and use the defaults defined in -#' the template file. Output will be doc `file` nonetheless. -#' @param section_properties `officer::prop_section` object. Here you can set margins and page -#' size. +#' @param template_file (`string`)\cr template file that `officer` will use as a starting point for the final +#' document. Document attaches the table and uses the defaults defined in the template file. +#' @param section_properties (`officer::prop_section`)\cr an [officer::prop_section()] object which sets margins and +#' page size. #' -#' @note `export_as_docx()` does not have many options available. We suggest, if you need -#' specific formats and details to use [tt_to_flextable()] first and then `export_as_docx`. -#' Only `title_as_header` and `footer_as_text` need to be specified again if changed in -#' `tt_to_flextable()`. +#' @note `export_as_docx()` has few customization options available. If you require specific formats and details, +#' we suggest that you use [tt_to_flextable()] prior to `export_as_docx`. Only the `title_as_header` and +#' `footer_as_text` parameters must be re-specified if the table is changed first using [tt_to_flextable()]. #' #' @seealso [tt_to_flextable()] #' @@ -609,7 +605,7 @@ formatters::export_as_pdf #' tf <- tempfile(fileext = ".docx") #' export_as_docx(tbl, file = tf, section_properties = section_properties_portrait()) #' } -#' @name export_as_docx +#' #' @export export_as_docx <- function(tt, file, @@ -696,7 +692,7 @@ add_text_par <- function(doc, chr_v, text_format) { doc } -#' @describeIn export_as_docx helper function that defines standard portrait properties for tables. +#' @describeIn export_as_docx Helper function that defines standard portrait properties for tables. #' @export section_properties_portrait <- function() { officer::prop_section( @@ -709,7 +705,7 @@ section_properties_portrait <- function() { ) } -#' @describeIn export_as_docx helper function that defines standard landscape properties for tables. +#' @describeIn export_as_docx Helper function that defines standard landscape properties for tables. #' @export section_properties_landscape <- function() { officer::prop_section( @@ -722,54 +718,47 @@ section_properties_landscape <- function() { ) } -#' @describeIn export_as_docx helper function that defines standard portrait margins for tables. +#' @describeIn export_as_docx Helper function that defines standard portrait margins for tables. #' @export margins_potrait <- function() { officer::page_mar(bottom = 0.98, top = 0.95, left = 1.5, right = 1, gutter = 0) } -#' @describeIn export_as_docx helper function that defines standard landscape margins for tables. +#' @describeIn export_as_docx Helper function that defines standard landscape margins for tables. #' @export margins_landscape <- function() { officer::page_mar(bottom = 1, top = 1.5, left = 0.98, right = 0.95, gutter = 0) } -#' Create a `FlexTable` from an `rtables` table +#' Create a `flextable` from an `rtables` table #' -#' @description #' Principally used for export ([export_as_docx()]), this function produces a `flextable` #' from an `rtables` table. If `theme = NULL`, `rtables`-like style will be used. Otherwise, #' [theme_docx_default()] will produce a `.docx`-friendly table. #' #' @inheritParams gen_args -#' @param theme function(1). Defaults to `theme_docx_default(tt)`. It expects a -#' a theme function that is designed internally as a function of a `flextable` object -#' and changes its layout and style. If set to `NULL`, it will produce a table similar -#' to `rtables` default. -#' @param border `officer` border object. Defaults to `officer::fp_border(width = 0.5)`. -#' @param indent_size integer(1). If `NULL`, the default indent size of the table (see -#' [matrix_form()] `indent_size`) is used. To work with `docx`, any size is multiplied -#' by 2 mm (5.67 pt) as default. -#' @param titles_as_header logical(1). Defaults to `TRUE` for [tt_to_flextable()], so the -#' table is self-contained as it makes additional header rows for [main_title()] -#' string and [subtitles()] character vector (one per element). `FALSE` is suggested -#' for [export_as_docx()]. This adds titles and subtitles as a text paragraph above -#' the table. Same style is applied. -#' @param footers_as_text logical(1). Defaults to `FALSE` for [tt_to_flextable()], so -#' the table is self-contained with the `flextable` definition of footnotes. `TRUE` is -#' used for [export_as_docx()] to add the footers as a new paragraph after the table. -#' Same style is applied, but with a smaller font. -#' @param counts_in_newline logical(1). Defaults to `FALSE`. In `rtables` text printing -#' ([formatters::toString()]), the column counts, i.e. `(N=xx)`, is always on a new line. -#' We noticed that for `docx` exports could be necessary to have it on the same line. -#' @param paginate logical(1). If you need `.docx` export and you use -#' `export_as_docx`, we suggest relying on `word` pagination system. Cooperation -#' between the two mechanisms is not guaranteed. This option splits `tt` in different -#' "pages" as multiple `flextables`. Defaults to `FALSE`. #' @inheritParams paginate_table -#' @param total_width numeric(1). Total width in inches for the resulting -#' `flextable(s)`. Defaults to 10. +#' @param theme (`function` or `NULL`)\cr A theme function that is designed internally as a function of a `flextable` +#' object to change its layout and style. If `NULL`, it will produce a table similar to `rtables` default. Defaults +#' to `theme_docx_default(tt)`. +#' @param border (`officer` border object)\cr defaults to `officer::fp_border(width = 0.5)`. +#' @param indent_size (`integer(1)`)\cr if `NULL`, the default indent size of the table (see [matrix_form()] +#' `indent_size`) is used. To work with `docx`, any size is multiplied by 2 mm (5.67 pt) by default. +#' @param titles_as_header (`flag`)\cr defaults to `TRUE` for [tt_to_flextable()], so the table is self-contained +#' as it makes additional header rows for [main_title()] string and [subtitles()] character vector (one per element). +#' `FALSE` is suggested for [export_as_docx()]. This adds titles and subtitles as a text paragraph above the table. +#' The same style is applied. +#' @param footers_as_text (`flag`)\cr defaults to `FALSE` for [tt_to_flextable()], so the table is self-contained with +#' the `flextable` definition of footnotes. `TRUE` is used for [export_as_docx()] to add the footers as a new +#' paragraph after the table. The same style is applied, but with a smaller font. +#' @param counts_in_newline (`flag`)\cr defaults to `FALSE`. In `rtables` text printing ([formatters::toString()]), +#' the column counts, i.e. `(N=xx)`, are always on a new line. For `docx` exports it could be necessary to print it +#' on the same line. +#' @param paginate (`flag`)\cr when exporting `.docx` documents using `export_as_docx`, we suggest relying on the +#' Microsoft Word pagination system. If `TRUE`, this option splits `tt` into different "pages" as multiple +#' `flextables`. Cooperation between the two mechanisms is not guaranteed. Defaults to `FALSE`. +#' @param total_width (`numeric(1)`)\cr total width (in inches) for the resulting flextable(s). Defaults to 10. #' -#' @return a `flextable` object. +#' @return A `flextable` object. #' #' @seealso [export_as_docx()] #' @@ -796,7 +785,6 @@ margins_landscape <- function() { #' #' tt_to_flextable(tbl, theme = theme_docx_default(tbl, font_size = 7)) #' -#' @name tt_to_flextable #' @export tt_to_flextable <- function(tt, theme = theme_docx_default(tt), @@ -978,17 +966,16 @@ tt_to_flextable <- function(tt, flx } -#' @describeIn tt_to_flextable main theme function for [export_as_docx()] -#' @param font character(1). Defaults to `"Arial"`. If the font is not available, `flextable` -#' default is used. -#' @param font_size integer(1). Positive integerish value that defaults to 9. -#' @param bold character vector. It can be any combination of `c("header", "content_rows", -#' "label_rows")`. The first one renders all column names bold (not `topleft` content). -#' Second and third option use [rtables::make_row_df()] to render content or/and label -#' rows as bold. -#' @param bold_manual named list. List of indexes lists. See example for needed structure. -#' Accepted groupings/names are `c("header", "body")`. +#' @describeIn tt_to_flextable Main theme function for [export_as_docx()] +#' #' @inheritParams export_as_docx +#' @param font (`string`)\cr defaults to `"Arial"`. If the font is not available, `flextable` default is used. +#' @param font_size (`integer(1)`)\cr font size. Defaults to 9. +#' @param bold (`character`)\cr parts of the table text that should be in bold. Can be any combination of +#' `c("header", "content_rows", "label_rows")`. The first one renders all column names bold (not `topleft` content). +#' The second and third option use [rtables::make_row_df()] to render content or/and label rows as bold. +#' @param bold_manual (named `list` or `NULL`)\cr list of index lists. See example for needed structure. Accepted +#' groupings/names are `c("header", "body")`. #' #' @seealso [export_as_docx()] #' @@ -1101,11 +1088,13 @@ theme_docx_default <- function(tt = NULL, # Option for more complicated stuff flx } } + # Padding helper functions to transform mm to pt and viceversa # # General note for word: 1pt -> 0.3527777778mm -> 0.013888888888889" word_inch_to_pt <- function(inch) { # nocov inch / 0.013888888888889 # nocov } + word_mm_to_pt <- function(mm) { mm / 0.3527777778 } diff --git a/R/tt_from_df.R b/R/tt_from_df.R index 5132d7a4f..e49d4a9af 100644 --- a/R/tt_from_df.R +++ b/R/tt_from_df.R @@ -1,15 +1,11 @@ -#' Create `ElementaryTable` from data.frame +#' Create an `ElementaryTable` from a `data.frame` #' -#' @param df data.frame. -#' -#' @return an \code{ElementaryTable} object with unnested columns corresponding to -#' \code{names(df)} and row labels corresponding to \code{row.names(df)}. +#' @param df (`data.frame`)\cr a data frame. #' #' @details -#' If row names are not defined in `df` (or they are simple numbers), then the -#' row names are taken from the column `label_name`, if exists. If `label_name` exists, -#' then it is also removed from the original data. Remember that this behavior is -#' compatible with [as_result_df()], when `as_is = TRUE` and the row names are not unique. +#' If row names are not defined in `df` (or they are simple numbers), then the row names are taken from the column +#' `label_name`, if it exists. If `label_name` exists, then it is also removed from the original data. This behavior +#' is compatible with [as_result_df()], when `as_is = TRUE` and the row names are not unique. #' #' @seealso [as_result_df()] for the inverse operation. #' diff --git a/R/tt_paginate.R b/R/tt_paginate.R index 39d39a2d9..4a6eaa37a 100644 --- a/R/tt_paginate.R +++ b/R/tt_paginate.R @@ -10,13 +10,11 @@ ## Current behavior: paginate_ttree takes a TableTree object and ## returns a list of rtable (S3) objects for printing. - - -#' @exportMethod nlines #' @inheritParams formatters::nlines -#' @name formatters_methods +#' #' @rdname formatters_methods #' @aliases nlines,TableRow-method +#' @exportMethod nlines setMethod( "nlines", "TableRow", function(x, colwidths, max_width) { @@ -81,7 +79,6 @@ setMethod( } ) - #' @export #' @rdname formatters_methods setMethod( @@ -146,7 +143,6 @@ col_dfrow <- function(col, ) } - pos_to_path <- function(pos) { spls <- pos_splits(pos) vals <- pos_splvals(pos) @@ -163,19 +159,16 @@ pos_to_path <- function(pos) { path } - - # make_row_df --------------------------------------------------------------- -# + #' @inherit formatters::make_row_df #' -# #' @note the technically present root tree node is excluded from the summary -# #' returned by both \code{make_row_df} and \code{make_col_df}, as it is simply -# #' the row/column structure of \code{tt} and thus not useful for pathing or -# #' pagination. +# #' @note The technically present root tree node is excluded from the summary returned by both `make_row_df` and +# #' `make_col_df`, as it is simply the row/column structure of `tt` and thus not useful for pathing or pagination. +# #' +# #' @return a data.frame of row/column-structure information used by the pagination machinery. +# #' # #' @export -# #' @return a data.frame of row/column-structure information used by the -# #' pagination machinery. # #' @name make_row_df # #' @rdname make_row_df # #' @aliases make_row_df,VTableTree-method @@ -252,7 +245,6 @@ setMethod( indent <- indent + 1L } - if (NROW(content_table(tt)) > 0) { ct_tt <- content_table(tt) cind <- indent + indent_mod(ct_tt) @@ -281,7 +273,6 @@ setMethod( indent <- cind + 1 } - allkids <- tree_children(tt) newnsibs <- length(allkids) for (i in seq_along(allkids)) { @@ -317,6 +308,7 @@ setMethod( # #' @exportMethod make_row_df #' @inherit formatters::make_row_df +#' #' @export #' @rdname formatters_methods setMethod( @@ -399,7 +391,6 @@ setMethod( } ) - setGeneric("inner_col_df", function(ct, colwidths = NULL, visible_only = TRUE, @@ -410,14 +401,13 @@ setGeneric("inner_col_df", function(ct, standardGeneric("inner_col_df") }) - -#' Column Layout Summary +#' Column layout summary #' -#' Generate a structural summary of the columns of an -#' rtables table and return it as a data.frame. +#' Used for pagination. Generate a structural summary of the columns of an `rtables` table and return it as a +#' `data.frame`. #' -#' Used for Pagination #' @inheritParams formatters::make_row_df +#' #' @export make_col_df <- function(tt, colwidths = NULL, @@ -452,7 +442,6 @@ setMethod( } ) - setMethod( "inner_col_df", "LayoutColTree", function(ct, colwidths, visible_only, @@ -497,9 +486,6 @@ setMethod( } ) - - - ## THIS INCLUDES BOTH "table stub" (i.e. column label and top_left) AND ## title/subtitle!!!!! .header_rep_nlines <- function(tt, colwidths, max_width, verbose = FALSE) { @@ -552,61 +538,51 @@ setMethod( #' Pagination of a `TableTree` #' +#' Paginate an `rtables` table in the vertical and/or horizontal direction, as required for the specified page size. +#' +#' @inheritParams gen_args +#' @inheritParams paginate_table +#' @param lpp (`numeric(1)`)\cr maximum lines per page including (re)printed header and context rows. +#' @param min_siblings (`numeric(1)`)\cr minimum sibling rows which must appear on either side of pagination row for a +#' mid-subtable split to be valid. Defaults to 2. +#' @param nosplitin (`character`)\cr names of sub-tables where page-breaks are not allowed, regardless of other +#' considerations. Defaults to none. #' -#' Paginate an `rtables` table in the vertical and/or horizontal -#' direction, as required for the specified page size. +#' @return +#' * `pag_tt_indices` returns a list of paginated-groups of row-indices of `tt`. +#' * `paginate_table` returns the subtables defined by subsetting by the indices defined by `pag_tt_indices`. #' #' @details +#' `rtables` pagination is context aware, meaning that label rows and row-group summaries (content rows) are repeated +#' after (vertical) pagination, as appropriate. This allows the reader to immediately understand where they are in the +#' table after turning to a new page, but does also mean that a rendered, paginated table will take up more lines of +#' text than rendering the table without pagination would. #' -#' `rtables` pagination is context aware, meaning that label rows and -#' row-group summaries (content rows) are repeated after (vertical) -#' pagination, as appropriate. This allows the reader to immediately -#' understand where they are in the table after turning to a new page, -#' but does also mean that a rendered, paginated table will take up -#' more lines of text than rendering the table without pagination -#' would. -#' -#' Pagination also takes into account word-wrapping of title, footer, -#' column-label, and formatted cell value content. +#' Pagination also takes into account word-wrapping of title, footer, column-label, and formatted cell value content. #' -#' Vertical pagination information (pagination data.frame) is created -#' using (`make_row_df`) +#' Vertical pagination information (pagination `data.frame`) is created using (`make_row_df`). #' -#' Horizontal pagination is performed by creating a pagination -#' dataframe for the columns, and then applying the same algorithm -#' used for vertical pagination to it. +#' Horizontal pagination is performed by creating a pagination data frame for the columns, and then applying the same +#' algorithm used for vertical pagination to it. #' -#' If physical page size and font information are specified, these are -#' used to derive lines-per-page (`lpp`) and characters-per-page -#' (`cpp`) values. +#' If physical page size and font information are specified, these are used to derive lines-per-page (`lpp`) and +#' characters-per-page (`cpp`) values. #' #' The full multi-direction pagination algorithm then is as follows: #' -#' 0. Adjust `lpp` and `cpp` to account for rendered elements that are not rows (columns) +#' 0. Adjust `lpp` and `cpp` to account for rendered elements that are not rows (columns): #' - titles/footers/column labels, and horizontal dividers in the vertical pagination case #' - row-labels, table_inset, and top-left materials in the horizontal case -#' 1. Perform 'forced pagination' representing page-by row splits, generating 1 or more tables -#' 2. Perform vertical pagination separately on each table generated in (1) +#' 1. Perform 'forced pagination' representing page-by row splits, generating 1 or more tables. +#' 2. Perform vertical pagination separately on each table generated in (1). #' 3. Perform horizontal pagination **on the entire table** and apply the results to each table -#' page generated in (1)-(2) -#' 4. Return a list of subtables representing full bi-directional pagination +#' page generated in (1)-(2). +#' 4. Return a list of subtables representing full bi-directional pagination. #' -#' Pagination in both directions is done using the *Core Pagination Algorithm* -#' implemented in the `formatters` package: +#' Pagination in both directions is done using the *Core Pagination Algorithm* implemented in the `formatters` package: #' #' @inheritSection formatters::pagination_algo Pagination Algorithm #' -#' @inheritParams gen_args -#' @inheritParams paginate_table -#' @param lpp numeric. Maximum lines per page including (re)printed header and context rows -#' @param min_siblings numeric. Minimum sibling rows which must appear on either side of pagination row for a -#' mid-subtable split to be valid. Defaults to 2. -#' @param nosplitin character. List of names of sub-tables where page-breaks are not allowed, regardless of other -#' considerations. Defaults to none. -#' -#' @return for \code{pag_tt_indices} a list of paginated-groups of row-indices of \code{tt}. For \code{paginate_table}, -#' The subtables defined by subsetting by the indices defined by \code{pag_tt_indices}. -#' #' @examples #' s_summary <- function(x) { #' if (is.numeric(x)) { @@ -628,7 +604,6 @@ setMethod( #' } #' } #' -#' #' lyt <- basic_table() %>% #' split_cols_by(var = "ARM") %>% #' analyze(c("AGE", "SEX", "BEP01FL", "BMRKR1", "BMRKR2", "COUNTRY"), afun = s_summary) @@ -654,7 +629,8 @@ setMethod( #' #' @rdname paginate #' @export -pag_tt_indices <- function(tt, lpp = 15, +pag_tt_indices <- function(tt, + lpp = 15, min_siblings = 2, nosplitin = character(), colwidths = NULL, @@ -707,7 +683,6 @@ pag_tt_indices <- function(tt, lpp = 15, ) } - copy_title_footer <- function(to, from, newptitle) { main_title(to) <- main_title(from) subtitles(to) <- subtitles(from) @@ -772,15 +747,15 @@ setMethod( non_null_na <- function(x) !is.null(x) && is.na(x) -#' @aliases paginate_table -#' @param cpp numeric(1) or NULL. Width (in characters) of the pages for -#' horizontal pagination. `NA` (the default) indicates `cpp` should be inferred from -#' the page size; `NULL` indicates no horizontal pagination should be done -#' regardless of page size. #' @inheritParams formatters::vert_pag_indices #' @inheritParams formatters::page_lcpp #' @inheritParams formatters::toString +#' @param cpp (`numeric(1)` or `NULL`)\cr width (in characters) of the pages for horizontal pagination. +#' `NA` (the default) indicates `cpp` should be inferred from the page size; `NULL` indicates no horizontal +#' pagination should be done regardless of page size. +#' #' @rdname paginate +#' @aliases paginate_table #' @export paginate_table <- function(tt, page_type = "letter", @@ -886,7 +861,6 @@ paginate_table <- function(tt, verbose = verbose ) ## paginate_table apparently doesn't accept indent_size - res <- lapply( inds$pag_row_indices, function(ii) { diff --git a/R/tt_pos_and_access.R b/R/tt_pos_and_access.R index 58e89fd91..b914fb364 100644 --- a/R/tt_pos_and_access.R +++ b/R/tt_pos_and_access.R @@ -11,7 +11,6 @@ do_recursive_replace <- function(tab, path, incontent = FALSE, value) { ## rows recursive_replace(tab, path, value) ## incontent, rows, cols,value) } - ## different cases we want to support: ## 1. Replace entire children for a particular node/position in the tree ## 2. Replace entire rows at a particular (ElementaryTable) position within the @@ -119,16 +118,17 @@ col_fnotes_at_path <- function(ctree, path, fnotes) { ctree } -#' Insert Row at Path +#' Insert row at path #' -#' Insert a row into an existing table directly before or directly after an existing -#' data (i.e., non-content and non-label) row, specified by its path. +#' Insert a row into an existing table directly before or directly after an existing data (i.e., non-content and +#' non-label) row, specified by its path. #' #' @inheritParams gen_args -#' @param after logical(1). Should `value` be added as a row directly before (`FALSE`, -#' the default) or after (`TRUE`) the row specified by `path`. +#' @param after (`flag`)\cr whether `value` should be added as a row directly before (`FALSE`, the default) or after +#' (`TRUE`) the row specified by `path`. +#' +#' @seealso [DataRow()], [rrow()] #' -#' @export #' @examples #' lyt <- basic_table() %>% #' split_rows_by("COUNTRY", split_fun = keep_split_levels(c("CHN", "USA"))) %>% @@ -147,14 +147,15 @@ col_fnotes_at_path <- function(ctree, path, fnotes) { #' after = TRUE #' ) #' tbl3 -#' @seealso [DataRow()] [rrow()] - +#' +#' @export setGeneric("insert_row_at_path", signature = c("tt", "value"), function(tt, path, value, after = FALSE) { standardGeneric("insert_row_at_path") } ) + #' @rdname insert_row_at_path setMethod( "insert_row_at_path", c("VTableTree", "DataRow"), @@ -216,27 +217,22 @@ setMethod( } ) - -#' Label at Path +#' Label at path +#' +#' Accesses or sets the label at a path. #' -#' Gets or sets the label at a path #' @inheritParams gen_args -#' @details #' -#' If `path` resolves to a single row, the label for that row -#' is retrieved or set. If, instead, `path` resolves to a subtable, -#' the text for the row-label associated with that path is retrieved -#' or set. In the subtable case, if the label text is set to a non-NA -#' value, the `labelrow` will be set to visible, even if it was not before. -#' Similarly, if the label row text for a subtable is set to NA, -#' the label row will bet set to non-visible, so the row will not +#' @details +#' If `path` resolves to a single row, the label for that row is retrieved or set. If, instead, `path` resolves to a +#' subtable, the text for the row-label associated with that path is retrieved or set. In the subtable case, if the +#' label text is set to a non-`NA` value, the `labelrow` will be set to visible, even if it was not before. Similarly, +#' if the label row text for a subtable is set to `NA`, the label row will bet set to non-visible, so the row will not #' appear at all when the table is printed. #' -#' @note When changing the row labels for content rows, it is important to -#' path all the way to the \emph{row}. Paths ending in `"@content"` will -#' not exhibit the behavior you want, and are thus an error. See -#' \code{\link{row_paths}} for help determining the full paths to content -#' rows. +#' @note When changing the row labels for content rows, it is important to path all the way to the *row*. Paths +#' ending in `"@content"` will not exhibit the behavior you want, and are thus an error. See [row_paths()] for help +#' determining the full paths to content rows. #' #' @examples #' lyt <- basic_table() %>% @@ -249,10 +245,12 @@ setMethod( #' #' label_at_path(tbl, c("COUNTRY", "USA")) <- "United States" #' tbl +#' #' @export label_at_path <- function(tt, path) { obj_label(tt_at_path(tt, path)) } + #' @export #' @rdname label_at_path `label_at_path<-` <- function(tt, path, value) { @@ -268,16 +266,18 @@ label_at_path <- function(tt, path) { tt } - - -#' Get or set table elements at specified path +#' Access or set table elements at specified path +#' #' @inheritParams gen_args -#' @param \dots unused. +#' @param ... unused. +#' #' @export #' @rdname ttap setGeneric("tt_at_path", function(tt, path, ...) standardGeneric("tt_at_path")) -#' @export + #' @inheritParams tt_at_path +#' +#' @export #' @rdname int_methods setMethod( "tt_at_path", "VTableTree", @@ -313,10 +313,7 @@ setMethod( } ) -#' @export -#' @rdname ttap -#' -#' @note Setting `NULL` at a defined path removes the corresponding sub table. +#' @note Setting `NULL` at a defined path removes the corresponding sub-table. #' #' @examples #' # Accessing sub table. @@ -345,13 +342,16 @@ setMethod( #' tt_at_path(tbl3, path = c("SEX", "F", "BMRKR2")) <- sub_tbl #' tbl3 #' +#' @export +#' @rdname ttap setGeneric( "tt_at_path<-", function(tt, path, ..., value) standardGeneric("tt_at_path<-") ) + #' @export -#' @rdname int_methods #' @keywords internal +#' @rdname int_methods setMethod( "tt_at_path<-", c(tt = "VTableTree", value = "VTableTree"), function(tt, path, ..., value) { @@ -362,8 +362,8 @@ setMethod( ## this one removes the child at path from the parents list of children, ## because that is how lists behave. #' @export -#' @rdname int_methods #' @keywords internal +#' @rdname int_methods setMethod( "tt_at_path<-", c(tt = "VTableTree", value = "NULL"), function(tt, path, ..., value) { @@ -371,10 +371,9 @@ setMethod( } ) - #' @export -#' @rdname int_methods #' @keywords internal +#' @rdname int_methods setMethod( "tt_at_path<-", c(tt = "VTableTree", value = "TableRow"), function(tt, path, ..., value) { @@ -388,49 +387,43 @@ setMethod( } ) - -#' @name brackets +#' Retrieve and assign elements of a `TableTree` #' -#' @title Retrieve and assign elements of a `TableTree` +#' @param x (`TableTree`)\cr a `TableTree` object. +#' @param i (`numeric(1)`)\cr index. +#' @param j (`numeric(1)`)\cr index. +#' @param drop (`flag`)\cr whether the value in the cell should be returned if one cell is selected by the +#' combination of `i` and `j`. It is not possible to return a vector of values. To do so please consider using +#' [cell_values()]. Defaults to `FALSE`. +#' @param ... additional arguments. Includes: +#' \describe{ +#' \item{`keep_topleft`}{(`flag`) (`[` only) whether the top-left material for the table should be retained after +#' subsetting. Defaults to `TRUE` if all rows are included (i.e. subsetting was by column), and drops it +#' otherwise.} +#' \item{`keep_titles`}{(`flag`) whether title information should be retained. Defaults to `FALSE`.} +#' \item{`keep_footers`}{(`flag`) whether non-referential footer information should be retained. Defaults to +#' `keep_titles`.} +#' \item{`reindex_refs`}{(`flag`) whether referential footnotes should be re-indexed as if the resulting subset is +#' the entire table. Defaults to `TRUE`.} +#' } +#' @param value (`list`, `TableRow`, or `TableTree`)\cr replacement value. #' -#' @param x `TableTree` -#' @param i index -#' @param j index -#' @param drop logical(1). Should the value in the cell be returned if one -#' cell is selected by the combination of \code{i} and \code{j}. It is not possible -#' to return a vector of values. To do so please consider using [cell_values()]. -#' Defaults to \code{FALSE}. -#' @param \dots Includes -#' \describe{ -#' \item{\emph{keep_topleft}}{logical(1) (\code{[} only) Should the `top-left` -#' material for the table be retained after subsetting. Defaults to `TRUE` if -#' all rows are included (i.e. subsetting was by column), and drops it otherwise.} -#' \item{\emph{keep_titles}}{logical(1) Should title information be retained. Defaults to \code{FALSE}.} -#' \item{\emph{keep_footers}}{logical(1) Should non-referential footer -#' information be retained. Defaults to \code{keep_titles}.} -#' \item{\emph{reindex_refs}}{logical(1). Should referential footnotes be -#' re-indexed as if the resulting subset is the entire table. Defaults to -#' \code{TRUE}.} -#' } -#' @param value Replacement value (list, `TableRow`, or `TableTree`) -#' -#' @return a \code{TableTree} (or \code{ElementaryTable}) object, unless a -#' single cell was selected with \code{drop=TRUE}, in which case the (possibly -#' multi-valued) fully stripped raw value of the selected cell. +#' @details +#' By default, subsetting drops the information about title, subtitle, main footer, provenance footer, and `topleft`. +#' If only a column is selected and all rows are kept, the `topleft` information remains as default. Any referential +#' footnote is kept whenever the subset table contains the referenced element. #' -#' @details by default, subsetting drops the information about title, subtitle, -#' main footer, provenance footer, and `topleft`. If only a column is selected -#' and all rows are kept, the `topleft` information remains as default. Any -#' referential footnote is kept whenever the subset table contains the -#' referenced element. +#' @return A `TableTree` (or `ElementaryTable`) object, unless a single cell was selected with `drop = TRUE`, in which +#' case the (possibly multi-valued) fully stripped raw value of the selected cell. #' -#' @note subsetting always preserve the original order, even if provided -#' indexes do not preserve it. If sorting is needed, please consider -#' using `sort_at_path()`. Also note that `character` indices are treated as paths, -#' not vectors of names in both `[` and `[<-`. +#' @note +#' Subsetting always preserve the original order, even if provided indexes do not preserve it. If sorting is needed, +#' please consider using `sort_at_path()`. Also note that `character` indices are treated as paths, not vectors of +#' names in both `[` and `[<-`. #' -#' @seealso Regarding sorting: `sort_at_path()` and how to understand path -#' structure: `summarize_row_groups()`, and `summarize_col_groups()`. +#' @seealso +#' * [sort_at_path()] to understand sorting. +#' * [summarize_row_groups()] to understand path structure. #' #' @examples #' lyt <- basic_table( @@ -501,6 +494,7 @@ setMethod( #' # Note that order can not be changed with subsetting #' tbl[c(4, 3, 1), c(3, 1)] # It preserves order and wanted selection #' +#' @name brackets NULL #' @exportMethod [<- @@ -608,6 +602,7 @@ setMethod( ) #' @inheritParams brackets +#' #' @exportMethod [<- #' @rdname int_methods #' @keywords internal @@ -701,7 +696,6 @@ setMethod( } ) - ## small utility to transform any negative ## indices into positive ones, given j ## and total length @@ -712,7 +706,6 @@ setMethod( j } - path_collapse_sep <- "`" escape_name_padding <- function(x) { ret <- gsub("._[[", "\\._\\[\\[", x, fixed = TRUE) @@ -729,7 +722,6 @@ path_to_regex <- function(path) { }, ""), collapse = path_collapse_sep) } - .path_to_pos <- function(path, tt, distinct_ok = TRUE, cols = FALSE) { path <- path[!grepl("^(|root)$", path)] if (cols) { @@ -846,7 +838,6 @@ setMethod( } ) - setMethod( "subset_cols", c("InstantiatedColumnInfo", "numeric"), function(tt, j, newcinfo = NULL, keep_topleft = TRUE, ...) { @@ -906,9 +897,6 @@ setMethod( } ) - - - ## label rows ARE included in the count subset_by_rownum <- function(tt, i, @@ -999,7 +987,6 @@ subset_by_rownum <- function(tt, ret } - #' @exportMethod [ #' @rdname brackets setMethod( @@ -1067,8 +1054,6 @@ setMethod( } ) - - #' @exportMethod [ #' @rdname int_methods #' @keywords internal @@ -1108,7 +1093,6 @@ setMethod( } ) - #' @exportMethod [ #' @rdname int_methods #' @keywords internal @@ -1120,7 +1104,6 @@ setMethod( } ) - #' @exportMethod [ #' @rdname int_methods #' @keywords internal @@ -1197,6 +1180,7 @@ setMethod( #' @importFrom utils compareVersion setGeneric("tail", tail) + setMethod( "tail", "VTableTree", function(x, n = 6L, ...) { @@ -1209,6 +1193,7 @@ setMethod( ) setGeneric("head", head) + setMethod( "head", "VTableTree", function(x, n = 6L, ...) { @@ -1218,31 +1203,21 @@ setMethod( #' Retrieve cell values by row and column path #' -#' @rdname cell_values -#' #' @inheritParams gen_args -#' @param rowpath character. Path in row-split space to the desired row(s). Can -#' include \code{"@content"}. -#' @param colpath character. Path in column-split space to the desired -#' column(s). Can include \code{"*"}. -#' @param omit_labrows logical(1). Should label rows underneath \code{rowpath} -#' be omitted (\code{TRUE}, the default), or return empty lists of cell -#' "values" (\code{FALSE}). -#' -#' @return for \code{cell_values}, a \emph{list} (regardless of the type of -#' value the cells hold). if \code{rowpath} defines a path to a single row, -#' \code{cell_values} returns the list of cell values for that row, otherwise -#' a list of such lists, one for each row captured underneath \code{rowpath}. -#' This occurs after subsetting to \code{colpath} has occurred. +#' @param rowpath (`character`)\cr path in row-split space to the desired row(s). Can include `"@content"`. +#' @param colpath (`character`)\cr path in column-split space to the desired column(s). Can include `"*"`. +#' @param omit_labrows (`flag`)\cr whether label rows underneath `rowpath` should be omitted (`TRUE`, the default), +#' or return empty lists of cell "values" (`FALSE`). #' -#' For \code{value_at} the "unwrapped" value of a single cell, or an error, if -#' the combination of \code{rowpath} and \code{colpath} do not define the -#' location of a single cell in \code{tt}. +#' @return +#' * `cell_values` returns a `list` (regardless of the type of value the cells hold). If `rowpath` defines a path to +#' a single row, `cell_values` returns the list of cell values for that row, otherwise a list of such lists, one for +#' each row captured underneath `rowpath`. This occurs after subsetting to `colpath` has occurred. +#' * `value_at` returns the "unwrapped" value of a single cell, or an error, if the combination of `rowpath` and +#' `colpath` do not define the location of a single cell in `tt`. #' -#' @note \code{cell_values} will return a single cell's value wrapped in a list. -#' Use \code{value_at} to receive the "bare" cell value. -#' -#' @export +#' @note `cell_values` will return a single cell's value wrapped in a list. Use `value_at` to receive the "bare" cell +#' value. #' #' @examples #' lyt <- basic_table() %>% @@ -1272,7 +1247,6 @@ setMethod( #' ) #' cell_values(tbl, c("RACE", "ASIAN"), c("ARM", "A: Drug X", "SEX", "M")) #' -#' #' ## any arm, male columns from the ASIAN content (i.e. summary) row #' cell_values( #' tbl, c("RACE", "ASIAN", "@content"), @@ -1301,6 +1275,9 @@ setMethod( #' c("ARM", "B: Placebo", "SEX", "M") #' ) #' stopifnot(identical(cvlist[[1]], cvnolist)) +#' +#' @rdname cell_values +#' @export setGeneric("cell_values", function(tt, rowpath = NULL, colpath = NULL, omit_labrows = TRUE) { standardGeneric("cell_values") }) @@ -1344,8 +1321,6 @@ setMethod( } ) - - #' @rdname cell_values #' @export setGeneric("value_at", function(tt, rowpath = NULL, colpath = NULL) { @@ -1377,7 +1352,6 @@ setMethod( } ) - #' @rdname int_methods #' @keywords internal #' @exportMethod value_at @@ -1388,8 +1362,6 @@ setMethod( } ) - - .inner_cell_value <- function(tt, rowpath, colpath = NULL, @@ -1468,21 +1440,22 @@ setMethod( } #' Head and tail methods +#' #' @inheritParams utils::head -#' @param keep_topleft logical(1). If `TRUE` (the default), -#' top_left material for the table will be carried over to the -#' subset. -#' @param keep_titles logical(1). If `TRUE` (the default), -#' all title material for the table will be carried over to the -#' subset. -#' @param keep_footers logical(1). If `TRUE`, all footer material for the table -#' will be carried over to the subset. It defaults to `keep_titles`. -#' @param reindex_refs logical(1). Defaults to `FALSE`. If `TRUE`, -#' referential footnotes will be reindexed for the subset. +#' @param keep_topleft (`flag`)\cr if `TRUE` (the default), top_left material for the table will be carried over to the +#' subset. +#' @param keep_titles (`flag`)\cr if `TRUE` (the default), all title material for the table will be carried over to the +#' subset. +#' @param keep_footers (`flag`)\cr if `TRUE`, all footer material for the table will be carried over to the subset. It +#' defaults to `keep_titles`. +#' @param reindex_refs (`flag`)\cr defaults to `FALSE`. If `TRUE`, referential footnotes will be reindexed for the +#' subset. +#' #' @docType methods #' @export #' @rdname head_tail setGeneric("head") + #' @docType methods #' @export #' @rdname head_tail @@ -1511,6 +1484,7 @@ setMethod( #' @export #' @rdname head_tail setGeneric("tail") + #' @docType methods #' @export #' @rdname head_tail diff --git a/R/tt_showmethods.R b/R/tt_showmethods.R index 44de92f5e..ff37df50e 100644 --- a/R/tt_showmethods.R +++ b/R/tt_showmethods.R @@ -27,10 +27,6 @@ treestruct <- function(obj, ind = 0L) { invisible(NULL) } - - - - setGeneric( "ploads_to_str", function(x, collapse = ":") standardGeneric("ploads_to_str") @@ -68,7 +64,6 @@ setMethod( } ) - setMethod( "ploads_to_str", "ANY", function(x, collapse = ":") { @@ -76,7 +71,6 @@ setMethod( } ) - setGeneric("payloadmsg", function(spl) standardGeneric("payloadmsg")) setMethod( @@ -112,7 +106,6 @@ setMethod( function(spl) "all" ) - setMethod( "payloadmsg", "ANY", function(spl) { @@ -132,7 +125,6 @@ spldesc <- function(spl, value = "") { ) } - layoutmsg <- function(obj) { ## if(!is(obj, "VLayoutNode")) ## stop("how did a non layoutnode object get in docatlayout??") @@ -164,7 +156,6 @@ setMethod( } ) - setGeneric("spltype_abbrev", function(obj) standardGeneric("spltype_abbrev")) setMethod( @@ -177,7 +168,6 @@ setMethod( function(obj) paste("ref_group", obj@ref_group_value) ) - setMethod( "spltype_abbrev", "MultiVarSplit", function(obj) "vars" @@ -218,9 +208,6 @@ setMethod( function(obj) "** col-var analysis **" ) - - - docat_splitvec <- function(object, indent = 0) { if (indent > 0) { cat(rep(" ", times = indent), sep = "") @@ -253,7 +240,6 @@ setMethod( } ) - docat_predataxis <- function(object, indent = 0) { lapply(object, docat_splitvec) } @@ -267,7 +253,6 @@ setMethod( } ) - setMethod( "show", "PreDataRowLayout", function(object) { @@ -277,7 +262,6 @@ setMethod( } ) - setMethod( "show", "PreDataTableLayouts", function(object) { @@ -313,7 +297,6 @@ setMethod( } ) - #' @rdname int_methods setMethod("print", "VTableTree", function(x, ...) { msg <- toString(x, ...) @@ -327,7 +310,6 @@ setMethod("show", "VTableTree", function(object) { invisible(object) }) - setMethod("show", "TableRow", function(object) { cat(sprintf( "[%s indent_mod %d]: %s %s\n", diff --git a/R/tt_sort.R b/R/tt_sort.R index 6e762283f..b6d8cace7 100644 --- a/R/tt_sort.R +++ b/R/tt_sort.R @@ -1,12 +1,11 @@ #' Score functions for sorting `TableTrees` #' -#' @rdname score_funs -#' #' @inheritParams gen_args -#' @return A single numeric value indicating score according to the relevant -#' metric for \code{tt}, to be used when sorting. +#' +#' @return A single numeric value indicating score according to the relevant metric for `tt`, to be used when sorting. #' #' @export +#' @rdname score_funs cont_n_allcols <- function(tt) { ctab <- content_table(tt) if (NROW(ctab) == 0) { @@ -21,15 +20,13 @@ cont_n_allcols <- function(tt) { )) } -#' @rdname score_funs -#' -#' @param j numeric(1). Number of column used for scoring. +#' @param j (`numeric(1)`)\cr index of column used for scoring. #' -#' @seealso For examples and details please read main documentation -#' [sort_at_path()] and relevant vignette -#' (([Sorting and Pruning](https://insightsengineering.github.io/rtables/main/articles/sorting_pruning.html))) +#' @seealso For examples and details, please read the documentation for [sort_at_path()] and the +#' [Sorting and Pruning](https://insightsengineering.github.io/rtables/main/articles/sorting_pruning.html) vignette. #' #' @export +#' @rdname score_funs cont_n_onecol <- function(j) { function(tt) { ctab <- content_table(tt) @@ -43,86 +40,67 @@ cont_n_onecol <- function(j) { } } -#' Sorting a Table at a Specific Path +#' Sorting a table at a specific path #' -#' @description Main sorting function to order the substructure of a `TableTree` -#' at a particular Path in the table tree. +#' Main sorting function to order the sub-structure of a `TableTree` at a particular path in the table tree. #' #' @inheritParams gen_args -#' @param scorefun function. Scoring function, should accept the type of -#' children directly under the position at \code{path} (either `VTableTree`, -#' `VTableRow`, or `VTableNodeInfo`, which covers both) and return a numeric value +#' @param scorefun (`function`)\cr scoring function. Should accept the type of children directly under the position +#' at `path` (either `VTableTree`, `VTableRow`, or `VTableNodeInfo`, which covers both) and return a numeric value #' to be sorted. -#' @param decreasing logical(1). Should the the scores generated by -#' \code{scorefun} be sorted in decreasing order. If unset (the default of -#' \code{NA}), it is set to \code{TRUE} if the generated scores are numeric -#' and \code{FALSE} if they are characters. -#' @param na.pos character(1). What should be done with children (sub-trees/rows) -#' with \code{NA} scores. Defaults to \code{"omit"}, which removes them, other -#' allowed values are \code{"last"} and \code{"first"} which indicate where -#' they should be placed in the order. -#' @param .prev_path character. Internal detail, do not set manually. +#' @param decreasing (`flag`)\cr whether the scores generated by `scorefun` should be sorted in decreasing order. If +#' unset (the default of `NA`), it is set to `TRUE` if the generated scores are numeric and `FALSE` if they are +#' characters. +#' @param na.pos (`string`)\cr what should be done with children (sub-trees/rows) with `NA` scores. Defaults to +#' `"omit"`, which removes them. Other allowed values are `"last"` and `"first"`, which indicate where `NA` scores +#' should be placed in the order. +#' @param .prev_path (`character`)\cr internal detail, do not set manually. #' -#' @return A `TableTree` with the same structure as \code{tt} with the exception -#' that the requested sorting has been done at \code{path}. +#' @return A `TableTree` with the same structure as `tt` with the exception that the requested sorting has been done +#' at `path`. #' #' @details +#' `sort_at_path`, given a path, locates the (sub)table(s) described by the path (see below for handling of the `"*"` +#' wildcard). For each such subtable, it then calls `scorefun` on each direct child of the table, using the resulting +#' scores to determine their sorted order. `tt` is then modified to reflect each of these one or more sorting +#' operations. #' -#' `sort_at_path`, given a path, locates the (sub)table(s) described -#' by the path (see below for handling of the `"*"` wildcard). For -#' each such subtable, it then calls `scorefun` on each direct -#' child of the table, using the resulting scores to determine -#' their sorted order. `tt` is then modified to reflect each of -#' these one or more sorting operations. -#' -#' In `path`, a leading `"root"` element will be ignored, regardless -#' of whether this matches the object name (and thus actual root -#' path name) of `tt`. Including `"root"` in paths where it does not -#' match the name of `tt` may mask deeper misunderstandings of how -#' valid paths within a `TableTree` object correspond to the layout -#' used to originally declare it, which we encourage users to -#' avoid. +#' In `path`, a leading `"root"` element will be ignored, regardless of whether this matches the object name (and thus +#' actual root path name) of `tt`. Including `"root"` in paths where it does not match the name of `tt` may mask deeper +#' misunderstandings of how valid paths within a `TableTree` object correspond to the layout used to originally declare +#' it, which we encourage users to avoid. #' -#' `path` can include the "wildcard" \code{"*"} as a step, -#' which translates roughly to *any* node/branching element and means -#' that each child at that step will be \emph{separately} sorted based on -#' \code{scorefun} and the remaining \code{path} entries. This can occur -#' multiple times in a path. +#' `path` can include the "wildcard" `"*"` as a step, which translates roughly to *any* node/branching element and means +#' that each child at that step will be *separately* sorted based on `scorefun` and the remaining `path` entries. This +#' can occur multiple times in a path. #' -#' A list of valid (non-wildcard) paths can be seen in the `path` column -#' of the data.frame created by [make_row_df()] with the `visible_only` -#' argument set to `FALSE`. It can also be inferred from the summary -#' given by [table_structure()]. +#' A list of valid (non-wildcard) paths can be seen in the `path` column of the `data.frame` created by [make_row_df()] +#' with the `visible_only` argument set to `FALSE`. It can also be inferred from the summary given by +#' [table_structure()]. #' -#' Note that sorting needs a deeper understanding of table structure in -#' `rtables`. Please consider reading related vignette -#' ([Sorting and Pruning](https://insightsengineering.github.io/rtables/main/articles/sorting_pruning.html)) -#' and explore table structure with useful functions like [table_structure()] -#' and [row_paths_summary()]. It is also very important to understand the -#' difference between "content" rows and "data" rows. The first one analyzes -#' and describes the split variable generally and is generated with -#' [summarize_row_groups()], while the second one is commonly produced by -#' calling one of the various [analyze()] instances. +#' Note that sorting needs a deeper understanding of table structure in `rtables`. Please consider reading the related +#' vignette ([Sorting and Pruning](https://insightsengineering.github.io/rtables/main/articles/sorting_pruning.html)) +#' and explore table structure with useful functions like [table_structure()] and [row_paths_summary()]. It is also +#' very important to understand the difference between "content" rows and "data" rows. The first one analyzes and +#' describes the split variable generally and is generated with [summarize_row_groups()], while the second one is +#' commonly produced by calling one of the various [analyze()] instances. #' -#' Built-in score functions are [cont_n_allcols()] and [cont_n_onecol()]. -#' They are both working with content rows (coming from [summarize_row_groups()]) -#' while a custom score function needs to be used on `DataRow`s. Here, some -#' useful descriptor and accessor functions (coming from related vignette): -#' - [cell_values()] - Retrieves a named list of a `TableRow` or -#' `TableTree` object's values. -#' - [obj_name()] - Retrieves the name of an object. Note this can differ -#' from the label that is displayed (if any is) when printing. -#' - [obj_label()] - Retrieves the display label of an object. Note this -#' can differ from the name that appears in the path. -#' - [content_table()] - Retrieves a `TableTree` object's content table -#' (which contains its summary rows). -#' - [tree_children()] - Retrieves a `TableTree` object's direct children -#' (either subtables, rows or possibly a mix thereof, though that -#' should not happen in practice). +#' Built-in score functions are [cont_n_allcols()] and [cont_n_onecol()]. They are both working with content rows +#' (coming from [summarize_row_groups()]) while a custom score function needs to be used on `DataRow`s. Here, some +#' useful descriptor and accessor functions (coming from related vignette): +#' - [cell_values()] - Retrieves a named list of a `TableRow` or `TableTree` object's values. +#' - [obj_name()] - Retrieves the name of an object. Note this can differ from the label that is displayed (if any is) +#' when printing. +#' - [obj_label()] - Retrieves the display label of an object. Note this can differ from the name that appears in the +#' path. +#' - [content_table()] - Retrieves a `TableTree` object's content table (which contains its summary rows). +#' - [tree_children()] - Retrieves a `TableTree` object's direct children (either subtables, rows or possibly a mix +#' thereof, though that should not happen in practice). #' -#' @seealso score functions [cont_n_allcols()] and [cont_n_onecol()]; -#' [make_row_df()] and [table_structure()] for pathing information; -#' [tt_at_path()] to select a table's (sub)structure at a given path. +#' @seealso +#' * Score functions [cont_n_allcols()] and [cont_n_onecol()]. +#' * [make_row_df()] and [table_structure()] for pathing information. +#' * [tt_at_path()] to select a table's (sub)structure at a given path. #' #' @examples #' # Creating a table to sort @@ -181,11 +159,12 @@ sort_at_path <- function(tt, ## XXX hacky fix this!!! ## tt_at_path removes root even if actual root table isn't named root, we need to match that behavior - if(path[1] == "root") { + if (path[1] == "root") { ## always remove first root element but only add it to ## .prev_path (used for error reporting) if it actually matched the name - if(obj_name(tt) == "root") + if (obj_name(tt) == "root") { .prev_path <- c(.prev_path, path[1]) + } path <- path[-1] } if (identical(obj_name(tt), path[1])) { @@ -227,11 +206,14 @@ sort_at_path <- function(tt, ret <- newtab } return(ret) - } else if(!(curname %in% names(oldkids))) { - stop("Unable to find child(ren) '", - curname, "'\n\t occurred at path: ", - paste(c(.prev_path, path[seq_len(count)]), collapse = " -> "), - "\n Use 'make_row_df(obj, visible_only = TRUE)[, c(\"label\", \"path\", \"node_class\")]' or\n\ 'table_structure(obj)' to explore valid paths.") + } else if (!(curname %in% names(oldkids))) { + stop( + "Unable to find child(ren) '", + curname, "'\n\t occurred at path: ", + paste(c(.prev_path, path[seq_len(count)]), collapse = " -> "), + "\n Use 'make_row_df(obj, visible_only = TRUE)[, c(\"label\", \"path\", \"node_class\")]' or \n", + "'table_structure(obj)' to explore valid paths." + ) } subtree <- tree_children(subtree)[[curname]] backpath <- c(backpath, curpath[1]) diff --git a/R/tt_toString.R b/R/tt_toString.R index 5c25d8fa0..b7398e383 100644 --- a/R/tt_toString.R +++ b/R/tt_toString.R @@ -2,9 +2,6 @@ #' @importMethodsFrom formatters toString matrix_form nlines NULL - - - # toString ---- ## #' @export @@ -16,15 +13,13 @@ NULL ## #' @export ## setMethod("print", "ANY", base::print) - #' Convert an `rtable` object to a string #' #' @inheritParams formatters::toString #' @inheritParams gen_args #' @inherit formatters::toString -#' @exportMethod toString #' -#' @return a string representation of \code{x} as it appears when printed. +#' @return A string representation of `x` as it appears when printed. #' #' @examples #' library(dplyr) @@ -42,9 +37,10 @@ NULL #' tbl <- build_table(lyt, iris2) #' #' cat(toString(tbl, col_gap = 3)) +#' #' @rdname tostring -#' @name tostring -#' @aliases toString,VTableTree-method +#' @aliases tostring toString,VTableTree-method +#' @exportMethod toString setMethod("toString", "VTableTree", function(x, widths = NULL, col_gap = 3, @@ -66,13 +62,15 @@ setMethod("toString", "VTableTree", function(x, #' Table shells #' -#' A table shell is a rendering of the table which maintains the structure, but does not -#' display the values, rather displaying the formatting instructions for each cell. +#' A table shell is a rendering of the table which maintains the structure, but does not display the values, rather +#' displaying the formatting instructions for each cell. #' -#' @inheritParams tostring +#' @inheritParams formatters::toString #' @inheritParams gen_args -#' @return for `table_shell_str` the string representing the table shell, for `table_shell`, -#' `NULL`, as the function is called for the side effect of printing the shell to the console. +#' +#' @return +#' * `table_shell` returns `NULL`, as the function is called for the side effect of printing the shell to the console. +#' * `table_shell_str` returns the string representing the table shell. #' #' @seealso [value_formats()] for a matrix of formats for each cell in a table. #' @@ -136,43 +134,34 @@ table_shell_str <- function(tt, widths = NULL, col_gap = 3, hsep = default_hsep( ) } - -#' Transform `rtable` to a list of matrices which can be used for outputting +#' Transform an `rtable` to a list of matrices which can be used for outputting #' #' Although `rtables` are represented as a tree data structure when outputting the table to ASCII or HTML -#' it is useful to map the `rtable` to an in between state with the formatted cells in a matrix form. +#' it is useful to map the `rtable` to an in-between state with the formatted cells in a matrix form. #' #' @inheritParams gen_args -#' @param indent_rownames logical(1), if TRUE the column with the row names in -#' the `strings` matrix of has indented row names (strings pre-fixed) -#' @param 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} -#' -#' @export +#' @param indent_rownames (`flag`)\cr if `TRUE`, the column with the row names in the `strings` matrix of the output +#' has indented row names (strings pre-fixed). +#' @param expand_newlines (`flag`)\cr whether the matrix form generated should expand rows whose values contain +#' newlines into multiple 'physical' rows (as they will appear when rendered into ASCII). Defaults to `TRUE`. #' #' @details -#' -#' The strings in the return object are defined as follows: row labels are those -#' determined by \code{make_row_df} and cell values are determined using -#' \code{get_formatted_cells}. (Column labels are calculated using a -#' non-exported internal function. +#' The strings in the return object are defined as follows: row labels are those determined by `make_row_df` and cell +#' values are determined using `get_formatted_cells`. (Column labels are calculated using a non-exported internal +#' function. #' #' @return A list with the following elements: -#' \describe{ -#' \item{strings}{The content, as it should be printed, of the top-left -#' material, column headers, row labels , and cell values of \code{tt}} -#' \item{spans}{The column-span information for each print-string in the strings -#' matrix} -#' \item{aligns}{The text alignment for each print-string in the strings matrix} -#' \item{display}{Whether each print-string in the strings matrix should be -#' printed or not}. -#' \item{row_info}{the data.frame generated by \code{make_row_df}} -#' } -#' -#' With an additional \code{nrow_header} attribute indicating the number of -#' pseudo "rows" the column structure defines. +#' \describe{ +#' \item{`strings`}{The content, as it should be printed, of the top-left material, column headers, row labels, +#' and cell values of `tt`.} +#' \item{`spans`}{The column-span information for each print-string in the `strings` matrix.} +#' \item{`aligns`}{The text alignment for each print-string in the `strings` matrix.} +#' \item{`display`}{Whether each print-string in the strings matrix should be printed.} +#' \item{`row_info`}{The `data.frame` generated by `make_row_df`.} +#' } +#' +#' With an additional `nrow_header` attribute indicating the number of pseudo "rows" that the column structure defines. +#' #' @examples #' library(dplyr) #' @@ -193,6 +182,8 @@ table_shell_str <- function(tt, widths = NULL, col_gap = 3, hsep = default_hsep( #' tbl <- build_table(lyt, iris2) #' #' matrix_form(tbl) +#' +#' @export setMethod( "matrix_form", "VTableTree", function(obj, @@ -338,8 +329,6 @@ setMethod( ret } - - format_fnote_ref <- function(fn) { if (length(fn) == 0 || (is.list(fn) && all(vapply(fn, function(x) length(x) == 0, TRUE)))) { return("") @@ -358,7 +347,6 @@ format_fnote_ref <- function(fn) { } } - format_fnote_note <- function(fn) { if (length(fn) == 0 || (is.list(fn) && all(vapply(fn, function(x) length(x) == 0, TRUE)))) { return(character()) @@ -417,8 +405,6 @@ get_formatted_fnotes <- function(tt) { lst <- lst[keep] unique(vapply(lst, format_fnote_note, "")) - - ## , recursive = FALSE) ## rlst <- unlist(lapply(rows, row_footnotes)) ## lst <- @@ -433,7 +419,6 @@ get_formatted_fnotes <- function(tt) { ## allstrs[order(inds)] } - .do_tbl_h_piece2 <- function(tt) { coldf <- make_col_df(tt, visible_only = FALSE) remain <- seq_len(nrow(coldf)) @@ -462,6 +447,7 @@ get_formatted_fnotes <- function(tt) { } ) } + .pad_end <- function(lst, padto, ncols) { curcov <- sum(vapply(lst, cell_cspan, 0L)) if (curcov == padto) { @@ -471,7 +457,6 @@ get_formatted_fnotes <- function(tt) { c(lst, list(rcell("", colspan = padto - curcov))) } - .pad_tops <- function(chunks) { lens <- vapply(chunks, length, 1L) padto <- max(lens) @@ -524,8 +509,6 @@ get_formatted_fnotes <- function(tt) { toret } - - .tbl_header_mat <- function(tt) { rows <- .do_tbl_h_piece2(tt) ## (clyt) cinfo <- col_info(tt) @@ -550,8 +533,6 @@ get_formatted_fnotes <- function(tt) { }) ) - - if (disp_ccounts(cinfo)) { counts <- col_counts(cinfo) cformat <- colcount_format(cinfo) @@ -599,17 +580,16 @@ get_formatted_fnotes <- function(tt) { ) } - - # get formatted cells ---- -#' get formatted cells +#' Get formatted cells #' -#' @return the formatted print-strings for all (body) cells in \code{obj}. -#' @export #' @inheritParams gen_args -#' @param shell logical(1). Should the formats themselves be returned instead of the -#' values with formats applied. Defaults to \code{FALSE}. +#' @param shell (`flag`)\cr whether the formats themselves should be returned instead of the values with formats +#' applied. Defaults to `FALSE`. +#' +#' @return The formatted print-strings for all (body) cells in `obj`. +#' #' @examples #' library(dplyr) #' @@ -625,8 +605,11 @@ get_formatted_fnotes <- function(tt) { #' build_table(iris2) #' #' get_formatted_cells(tbl) +#' +#' @export #' @rdname gfc setGeneric("get_formatted_cells", function(obj, shell = FALSE) standardGeneric("get_formatted_cells")) + #' @rdname gfc setMethod( "get_formatted_cells", "TableTree", @@ -698,9 +681,9 @@ setMethod( } ) - #' @rdname gfc setGeneric("get_cell_aligns", function(obj) standardGeneric("get_cell_aligns")) + #' @rdname gfc setMethod( "get_cell_aligns", "TableTree", @@ -756,21 +739,17 @@ setMethod( } ) - - # utility functions ---- -#' from sequence remove numbers where diff == 1 -#' -#' numbers need to be sorted -#' -#' @noRd +#' From a sorted sequence of numbers, remove numbers where diff == 1 #' #' @examples #' remove_consecutive_numbers(x = c(2, 4, 9)) #' remove_consecutive_numbers(x = c(2, 4, 5, 9)) #' remove_consecutive_numbers(x = c(2, 4, 5, 6, 9)) #' remove_consecutive_numbers(x = 4:9) +#' +#' @noRd remove_consecutive_numbers <- function(x) { # actually should be integer stopifnot(is.wholenumber(x), is.numeric(x), !is.unsorted(x)) @@ -783,14 +762,13 @@ remove_consecutive_numbers <- function(x) { x[c(TRUE, diff(x) != 1)] } - -#' insert an empty string -#' -#' @noRd +#' Insert an empty string #' #' @examples #' empty_string_after(letters[1:5], 2) #' empty_string_after(letters[1:5], c(2, 4)) +#' +#' @noRd empty_string_after <- function(x, indices) { if (length(indices) > 0) { offset <- 0 @@ -802,23 +780,24 @@ empty_string_after <- function(x, indices) { x } -#' Indent Strings +#' Indent strings #' #' Used in rtables to indent row names for the ASCII output. #' -#' @param x a character vector -#' @param indent a vector of length \code{length(x)} with non-negative integers -#' @param incr non-negative integer: number of spaces per indent level -#' @param including_newline boolean: should newlines also be indented +#' @param x (`character`)\cr a character vector. +#' @param indent (`numeric`)\cr a vector of non-negative integers of length `length(x)`. +#' @param incr (`integer(1)`)\cr a non-negative number of spaces per indent level. +#' @param including_newline (`flag`)\cr whether newlines should also be indented. +#' +#' @return `x`, indented with left-padding with `indent * incr` white-spaces. #' -#' @export -#' @return \code{x} indented by left-padding with \code{indent*incr} white-spaces. #' @examples #' indent_string("a", 0) #' indent_string("a", 1) #' indent_string(letters[1:3], 0:2) #' indent_string(paste0(letters[1:3], "\n", LETTERS[1:3]), 0:2) #' +#' @export indent_string <- function(x, indent = 0, incr = 2, including_newline = TRUE) { if (length(x) > 0) { indent <- rep_len(indent, length.out = length(x)) @@ -840,7 +819,6 @@ indent_string <- function(x, indent = 0, incr = 2, including_newline = TRUE) { ## paste(na.omit(x), ...) ## } - ## #' Pad a string and align within string ## #' ## #' @param x string @@ -888,25 +866,23 @@ indent_string <- function(x, indent = 0, incr = 2, including_newline = TRUE) { ## strrep(" ", n) ## } - -#' Convert Matrix of Strings into a String with Aligned Columns +#' Convert matrix of strings into a string with aligned columns #' -#' Note that this function is intended to print simple rectangular -#' matrices and not rtables. +#' Note that this function is intended to print simple rectangular matrices and not `rtable`s. #' -#' @param mat a matrix of strings -#' @param nheader number of header rows -#' @param colsep string that separates the columns -#' @param hsep character to build line separator +#' @param mat (`matrix`)\cr a matrix of strings. +#' @param nheader (`integer(1)`)\cr number of header rows. +#' @param colsep (`string`)\cr a string that separates the columns. +#' @param hsep (`character(1)`)\cr character to build line separator. #' -#' @noRd -#' -#' @return a string +#' @return A string. #' #' @examples #' mat <- matrix(c("A", "B", "C", "a", "b", "c"), nrow = 2, byrow = TRUE) #' cat(mat_as_string(mat)) #' cat("\n") +#' +#' @noRd mat_as_string <- function(mat, nheader = 1, colsep = " ", hsep = default_hsep()) { colwidths <- apply(apply(mat, c(1, 2), nchar), 2, max) diff --git a/R/utils.R b/R/utils.R index 0b93413a2..09c3afefb 100644 --- a/R/utils.R +++ b/R/utils.R @@ -1,12 +1,13 @@ #' Check if an object is a valid `rtable` #' -#' @param x an object +#' @param x (`ANY`)\cr an object. #' +#' @return `TRUE` if `x` is a formal `TableTree` object, `FALSE` otherwise. #' -#' @export -#' @return \code{TRUE} if \code{x} is a formal Table object, \code{FALSE} otherwise. #' @examples #' is_rtable(build_table(basic_table(), iris)) +#' +#' @export is_rtable <- function(x) { is(x, "VTableTree") } @@ -74,12 +75,11 @@ func_takes <- function(func, params, is_first = FALSE) { } } -#' Translate spl_context to Path for display in error messages +#' Translate spl_context to a path to display in error messages #' -#' @param ctx data.frame. The `spl_context` data.frame where the error occurred +#' @param ctx (`data.frame`)\cr the `spl_context` data frame where the error occurred. #' -#' @return A character string containing a description of the row path corresponding -#' to the `ctx` +#' @return A character string containing a description of the row path corresponding to `ctx`. #' #' @export spl_context_to_disp_path <- function(ctx) { diff --git a/R/validate_table_struct.R b/R/validate_table_struct.R index 1c899c2fa..3cf213d8e 100644 --- a/R/validate_table_struct.R +++ b/R/validate_table_struct.R @@ -1,18 +1,19 @@ -#' Find degenerate (sub)structures within a table (Experimental) -#' @param tt `TableTree` +#' Find degenerate (sub)structures within a table #' -#' This function returns a list with the row-paths to all -#' structural subtables which contain no data rows ( -#' even if they have associated content rows). +#' @description `r lifecycle::badge("experimental")` #' -#' @return a list of character vectors representing the -#' row paths, if any, to degenerate substructures within -#' the table. +#' This function returns a list with the row-paths to all structural subtables which contain no data rows (even if +#' they have associated content rows). +#' +#' @param tt (`TableTree`)\cr a `TableTree` object. +#' +#' @return A list of character vectors representing the row paths, if any, to degenerate substructures within the table. #' -#' @export #' @examples #' find_degen_struct(rtable("hi")) #' +#' @family table structure validation functions +#' @export find_degen_struct <- function(tt) { degen <- list() @@ -32,38 +33,38 @@ find_degen_struct <- function(tt) { degen } -#' Validate and Assert valid table structure (Experimental). +#' Validate and assert valid table structure #' -#' @param tt `TableTree` +#' @description `r lifecycle::badge("experimental")` #' -#' A `TableTree` (`rtables`-built table) is considered degenerate if +#' A `TableTree` (`rtables`-built table) is considered degenerate if: #' \enumerate{ -#' \item{it contains no subtables or data rows (content rows do not count)} -#' \item{it contains a subtable which is degenerate by the criterion above} +#' \item{It contains no subtables or data rows (content rows do not count).} +#' \item{It contains a subtable which is degenerate by the criterion above.} #' } #' -#' `validate_table_struct` assesses whether `tt` has a valid (non-degenerate) -#' structure. +#' `validate_table_struct` assesses whether `tt` has a valid (non-degenerate) structure. #' -#' `assert_valid_table` asserts a table must have a valid structure, -#' and throws an informative error (the default) or warning (if `warn_only` -#' is `TRUE`) if the table is degenerate (has invalid structure or -#' contains one or more invalid substructures +#' `assert_valid_table` asserts a table must have a valid structure, and throws an informative error (the default) or +#' warning (if `warn_only` is `TRUE`) if the table is degenerate (has invalid structure or contains one or more +#' invalid substructures. #' -#' @return for `validate_table_struct` a logical value indicating valid structure; -#' `assert_valid_table` is called for its side-effect of throwing an error -#' or warning for degenerate tables. +#' @param tt (`TableTree`)\cr a `TableTree` object. #' -#' @note This function is experimental and the exact text of the warning/error -#' is subject to change in future releases. +#' @return +#' * `validate_table_struct` returns a logical value indicating valid structure. +#' * `assert_valid_table` is called for its side-effect of throwing an error or warning for degenerate tables. #' -#' @export +#' @note This function is experimental and the exact text of the warning/error is subject to change in future releases. #' #' @examples #' validate_table_struct(rtable("hahaha")) #' \dontrun{ #' assert_valid_table(rtable("oops")) #' } +#' +#' @family table structure validation functions +#' @export validate_table_struct <- function(tt) { degen_pths <- find_degen_struct(tt) length(degen_pths) == 0 @@ -129,11 +130,10 @@ make_degen_message <- function(degen_pths, tt) { msg } - +#' @param warn_only (`flag`)\cr whether a warning should be thrown instead of an error. Defaults to `FALSE`. +#' #' @rdname validate_table_struct #' @export -#' @param warn_only logical(1). Should a warning be thrown instead of an error? -#' Defaults to `FALSE` assert_valid_table <- function(tt, warn_only = FALSE) { degen_pths <- find_degen_struct(tt) if (length(degen_pths) == 0) { @@ -141,7 +141,6 @@ assert_valid_table <- function(tt, warn_only = FALSE) { } ## we failed, now we build an informative error/warning message - msg <- make_degen_message(degen_pths, tt) if (!warn_only) { @@ -151,29 +150,23 @@ assert_valid_table <- function(tt, warn_only = FALSE) { return(FALSE) } - -#' Sanitize degenerate table structures (Experimental) +#' Sanitize degenerate table structures #' +#' @description `r lifecycle::badge("experimental")` #' -#' @description Experimental function to correct structure -#' of degenerate tables by adding messaging rows to empty -#' sub-structures. +#' Experimental function to correct structure of degenerate tables by adding messaging rows to empty sub-structures. #' -#' @param tt `TableTree` -#' @param empty_msg character(1). The string which should be spanned across -#' the inserted empty rows. +#' @param tt (`TableTree`)\cr a `TableTree` object. +#' @param empty_msg (`string`)\cr the string which should be spanned across the inserted empty rows. #' #' @details +#' This function locates degenerate portions of the table (including the table overall in the case of a table with no +#' data rows) and inserts a row which spans all columns with the message `empty_msg` at each one, generating a table +#' guaranteed to be non-degenerate. #' -#' This function locates degenerate portions of the table (including the table -#' overall in the case of a table with no data rows) and inserts a row -#' which spans all columns with the message `empty_msg` at each one, -#' generating a table guaranteed to be non-degenerate. -#' -#' @return If `tt` is already valid, it is returned unmodified. If `tt` is -#' degenerate, a modified, non-degenerate version of the table is returned. +#' @return If `tt` is already valid, it is returned unmodified. If `tt` is degenerate, a modified, non-degenerate +#' version of the table is returned. #' -#' @export #' @examples #' sanitize_table_struct(rtable("cool beans")) #' @@ -185,6 +178,9 @@ assert_valid_table <- function(tt, warn_only = FALSE) { #' ## Degenerate because it doesn't have any analyze calls -> no data rows #' badtab <- build_table(lyt, DM) #' sanitize_table_struct(badtab) +#' +#' @family table structure validation functions +#' @export sanitize_table_struct <- function(tt, empty_msg = "-- This Section Contains No Data --") { rdf <- make_row_df(tt) diff --git a/_pkgdown.yml b/_pkgdown.yml index b87bd7d83..52ae63cef 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -177,7 +177,6 @@ reference: - row_paths - row_paths_summary - table_structure - - summarize_rows - table_shell - formatters::make_row_df - make_col_df @@ -208,7 +207,6 @@ reference: contents: - prune_table - all_zero_or_na - - trim_zero_rows - trim_rows - sort_at_path - cont_n_allcols @@ -288,7 +286,7 @@ reference: - row_footnotes - update_ref_indexing - - title: Result Dataframe Functions + - title: Result Data Frame Functions desc: Functions for generating result data frames from rtables TableTree objects contents: - as_result_df diff --git a/inst/WORDLIST b/inst/WORDLIST index ece47f93b..0274737d2 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -1,83 +1,87 @@ -amongst -Arg +Bové +CRAN's Carreras -charset Cheatsheet Chohan +FFFL +Godwin +Heng +Hoffmann +Kelkhoff +Layouting +Lewandowski +Maximo +Modelling +NSE +Paszty +Pharma +Phuse +Pre +Qi +RStudio +Resync +Rua +STUDYID +Sabanés +Saibah +Stoilova +Subtable +Subtables +Tadeusz +Unstratified +Yung +amongst +charset combinatorial -CRAN's customizations +de decrementing dimensioned dplyr emph facetted facetting -FFFL +flextable formatter +funder +funs getter getters -Godwin -Heng ing initializer -integerish iteratively -Kelkhoff labelled -Layouting layouting -Lewandowski mandatorily -Maximo -Modelling multivariable -NSE orderable -Paszty +params pathing -Pharma -Phuse postfix -Postprocessing postprocessing -Pre pre priori programmatically -Qi quartiles reindexed repo repped responder -Resync reusability roadmap -RStudio -rtables -Saibah sortable spl -Stoilova -STUDYID -Subtable +subsplits subtable subtable's -Subtables subtables summarization tableone -TableTree -Tadeusz todo unaggregated unicode univariable -unnested unpruned -Unstratified unstratified useR xtable -Yung diff --git a/man/CellValue.Rd b/man/CellValue.Rd index 6fa05b9ce..e2627590d 100644 --- a/man/CellValue.Rd +++ b/man/CellValue.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/00tabletrees.R \name{CellValue} \alias{CellValue} -\title{Cell Value constructor} +\title{Constructor for Cell Value} \usage{ CellValue( val, @@ -16,38 +16,32 @@ CellValue( ) } \arguments{ -\item{val}{ANY. value in the cell exactly as it should be passed to a -formatter or returned when extracted} +\item{val}{(\code{ANY})\cr value in the cell exactly as it should be passed to a formatter or returned when extracted.} -\item{format}{\code{FormatSpec}. Format associated with this split. Formats can be -declared via strings (\code{"xx.x"}) or function. In cases such as -\code{analyze} calls, they can character vectors or lists of functions.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr format associated with this split. Formats can be declared via +strings (\code{"xx.x"}) or function. In cases such as \code{analyze} calls, they can be character vectors or lists of +functions. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for a list of all available format strings.} -\item{colspan}{integer(1). Column span value.} +\item{colspan}{(\code{integer(1)})\cr column span value.} -\item{label}{character(1). A label (not to be confused with the name) for the -object/structure.} +\item{label}{(\code{string})\cr a label (not to be confused with the name) for the object/structure.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} -\item{footnotes}{list or \code{NULL}. Referential footnote messages for the cell.} +\item{footnotes}{(\code{list} or \code{NULL})\cr referential footnote messages for the cell.} -\item{align}{character(1) or \code{NULL}. Alignment the value should be rendered with. -It defaults to \code{"center"} if \code{NULL} is used. See \code{\link[formatters:list_formats]{formatters::list_valid_aligns()}} -for currently supported alignments.} +\item{align}{(\code{string} or \code{NULL})\cr alignment the value should be rendered with. Defaults to \code{"center"} if +\code{NULL} is used. See \code{\link[formatters:list_formats]{formatters::list_valid_aligns()}} for all currently supported alignments.} -\item{format_na_str}{character(1). String which should be displayed when -formatted if this cell's value(s) are all NA.} +\item{format_na_str}{(\code{string})\cr string which should be displayed when formatted if this cell's value(s) +are all \code{NA}.} } \value{ -An object representing the value within a single cell within a -populated table. The underlying structure of this object is an -implementation detail and should not be relied upon beyond calling -accessors for the class. +An object representing the value within a single cell within a populated table. The underlying structure +of this object is an implementation detail and should not be relied upon beyond calling accessors for the class. } \description{ -Cell Value constructor +Constructor for Cell Value } diff --git a/man/ManualSplit.Rd b/man/ManualSplit.Rd index 9c86820c7..00b6314b6 100644 --- a/man/ManualSplit.Rd +++ b/man/ManualSplit.Rd @@ -19,46 +19,38 @@ ManualSplit( ) } \arguments{ -\item{levels}{character. Levels of the split (i.e. the children of the manual -split)} +\item{levels}{(\code{character})\cr levels of the split (i.e. the children of the manual split).} -\item{label}{character(1). A label (not to be confused with the name) for the -object/structure.} +\item{label}{(\code{string})\cr a label (not to be confused with the name) for the object/structure.} -\item{name}{character(1). Name of the split/table/row being created. Defaults -to same as the corresponding label, but is not required to be.} +\item{name}{(\code{string})\cr name of the split/table/row being created. Defaults to the value of the +corresponding label, but is not required to be.} -\item{extra_args}{list. Extra arguments to be passed to the tabulation -function. Element position in the list corresponds to the children of this -split. Named elements in the child-specific lists are ignored if they do +\item{extra_args}{(\code{list})\cr extra arguments to be passed to the tabulation function. Element position in the list +corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do not match a formal argument of the tabulation function.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} -\item{cindent_mod}{numeric(1). The indent modifier for the content tables -generated by this split.} +\item{cindent_mod}{(\code{numeric(1)})\cr the indent modifier for the content tables generated by this split.} -\item{cvar}{character(1). The variable, if any, which the content function -should accept. Defaults to NA.} +\item{cvar}{(\code{string})\cr the variable, if any, that the content function should accept. Defaults to \code{NA}.} -\item{cextra_args}{list. Extra arguments to be passed to the content function -when tabulating row group summaries.} +\item{cextra_args}{(\code{list})\cr extra arguments to be passed to the content function when tabulating row group +summaries.} -\item{label_pos}{character(1). Location the variable label should be -displayed, Accepts \code{"hidden"} (default for non-analyze row splits), \code{"visible"}, -\code{"topleft"}, and - for analyze splits only - \code{"default"}. For analyze calls, -\code{"default"} indicates that the variable should be visible if and only if -multiple variables are analyzed at the same level of nesting.} +\item{label_pos}{(\code{string})\cr location where the variable label should be displayed. Accepts \code{"hidden"} +(default for non-analyze row splits), \code{"visible"}, \code{"topleft"}, and \code{"default"} (for analyze splits only). For +\code{analyze} calls, \code{"default"} indicates that the variable should be visible if and only if multiple variables are +analyzed at the same level of nesting.} -\item{page_prefix}{character(1). Prefix, to be appended with the split value, -when forcing pagination between the children of this split/table} +\item{page_prefix}{(\code{string})\cr prefix to be appended with the split value when forcing pagination between +the children of a split/table.} -\item{section_div}{character(1). String which should be repeated as a section -divider after each group defined by this split instruction, or -\code{NA_character_} (the default) for no section divider.} +\item{section_div}{(\code{string})\cr string which should be repeated as a section divider after each group defined +by this split instruction, or \code{NA_character_} (the default) for no section divider.} } \value{ A \code{ManualSplit} object. diff --git a/man/MultiVarSplit.Rd b/man/MultiVarSplit.Rd index 08fef1c22..149ce8642 100644 --- a/man/MultiVarSplit.Rd +++ b/man/MultiVarSplit.Rd @@ -28,75 +28,62 @@ MultiVarSplit( ) } \arguments{ -\item{vars}{character vector. Multiple variable names.} +\item{vars}{(\code{character})\cr vector of variable names.} -\item{split_label}{string. Label string to be associated with the table -generated by the split. Not to be confused with labels assigned to each -child (which are based on the data and type of split during tabulation).} +\item{split_label}{(\code{string})\cr label to be associated with the table generated by the split. Not to be confused +with labels assigned to each child (which are based on the data and type of split during tabulation).} -\item{varlabels}{character vector. Labels for \code{vars}} +\item{varlabels}{(\code{character})\cr vector of labels for \code{vars}.} -\item{varnames}{character vector. Names for \code{vars} which will appear in -pathing. When \code{vars} are all unique this will be the variable names. -If not, these will be variable names with suffixes as necessary to enforce +\item{varnames}{(\code{character})\cr vector of names for \code{vars} which will appear in pathing. When \code{vars} are all +unique this will be the variable names. If not, these will be variable names with suffixes as necessary to enforce uniqueness.} -\item{cfun}{list/function/NULL. tabulation function(s) for creating content -rows. Must accept \code{x} or \code{df} as first parameter. Must accept -\code{labelstr} as the second argument. Can optionally accept all optional -arguments accepted by analysis functions. See \code{\link{analyze}}.} +\item{cfun}{(\code{list}, \code{function}, or \code{NULL})\cr tabulation function(s) for creating content rows. Must accept \code{x} +or \code{df} as first parameter. Must accept \code{labelstr} as the second argument. Can optionally accept all optional +arguments accepted by analysis functions. See \code{\link[=analyze]{analyze()}}.} -\item{cformat}{format spec. Format for content rows} +\item{cformat}{(\code{string}, \code{function}, or \code{list})\cr format for content rows.} -\item{cna_str}{character. NA string for use with \code{cformat} for content -table.} +\item{cna_str}{(\code{character})\cr NA string for use with \code{cformat} for content table.} -\item{split_format}{\code{FormatSpec}. Default format associated with the split -being created.} +\item{split_format}{(\code{string}, \code{function}, or \code{list})\cr default format associated with the split being created.} -\item{split_na_str}{character. NA string vector for use with \code{split_format}.} +\item{split_na_str}{(\code{character})\cr NA string vector for use with \code{split_format}.} -\item{split_name}{string. Name associated with this split (for pathing, etc)} +\item{split_name}{(\code{string})\cr name associated with the split (for pathing, etc.).} -\item{child_labels}{string. One of \code{"default"}, \code{"visible"}, -\code{"hidden"}. What should the display behavior be for the labels (i.e. -label rows) of the children of this split. Defaults to \code{"default"} -which flags the label row as visible only if the child has 0 content rows.} +\item{child_labels}{(\code{string})\cr the display behavior for the labels (i.e. label rows) of the children of this +split. Accepts \code{"default"}, \code{"visible"}, and \code{"hidden"}. Defaults to \code{"default"} which flags the label row as +visible only if the child has 0 content rows.} -\item{extra_args}{list. Extra arguments to be passed to the tabulation -function. Element position in the list corresponds to the children of this -split. Named elements in the child-specific lists are ignored if they do +\item{extra_args}{(\code{list})\cr extra arguments to be passed to the tabulation function. Element position in the list +corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do not match a formal argument of the tabulation function.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} -\item{cindent_mod}{numeric(1). The indent modifier for the content tables -generated by this split.} +\item{cindent_mod}{(\code{numeric(1)})\cr the indent modifier for the content tables generated by this split.} -\item{cvar}{character(1). The variable, if any, which the content function -should accept. Defaults to NA.} +\item{cvar}{(\code{string})\cr the variable, if any, that the content function should accept. Defaults to \code{NA}.} -\item{cextra_args}{list. Extra arguments to be passed to the content function -when tabulating row group summaries.} +\item{cextra_args}{(\code{list})\cr extra arguments to be passed to the content function when tabulating row group +summaries.} -\item{label_pos}{character(1). Location the variable label should be -displayed, Accepts \code{"hidden"} (default for non-analyze row splits), \code{"visible"}, -\code{"topleft"}, and - for analyze splits only - \code{"default"}. For analyze calls, -\code{"default"} indicates that the variable should be visible if and only if -multiple variables are analyzed at the same level of nesting.} +\item{label_pos}{(\code{string})\cr location where the variable label should be displayed. Accepts \code{"hidden"} +(default for non-analyze row splits), \code{"visible"}, \code{"topleft"}, and \code{"default"} (for analyze splits only). For +\code{analyze} calls, \code{"default"} indicates that the variable should be visible if and only if multiple variables are +analyzed at the same level of nesting.} -\item{split_fun}{function/NULL. custom splitting function See -\code{\link{custom_split_funs}}} +\item{split_fun}{(\code{function} or \code{NULL})\cr custom splitting function. See \link{custom_split_funs}.} -\item{page_prefix}{character(1). Prefix, to be appended with the split value, -when forcing pagination between the children of this split/table} +\item{page_prefix}{(\code{string})\cr prefix to be appended with the split value when forcing pagination between +the children of a split/table.} -\item{section_div}{character(1). String which should be repeated as a section -divider after each group defined by this split instruction, or -\code{NA_character_} (the default) for no section divider.} +\item{section_div}{(\code{string})\cr string which should be repeated as a section divider after each group defined +by this split instruction, or \code{NA_character_} (the default) for no section divider.} } \value{ A \code{MultiVarSplit} object. diff --git a/man/VarLevelSplit.Rd b/man/VarLevelSplit.Rd index a9dd9d797..5a1233214 100644 --- a/man/VarLevelSplit.Rd +++ b/man/VarLevelSplit.Rd @@ -49,82 +49,66 @@ VarLevWBaselineSplit( ) } \arguments{ -\item{var}{string, variable name} +\item{var}{(\code{string})\cr variable name.} -\item{split_label}{string. Label string to be associated with the table -generated by the split. Not to be confused with labels assigned to each -child (which are based on the data and type of split during tabulation).} +\item{split_label}{(\code{string})\cr label to be associated with the table generated by the split. Not to be confused +with labels assigned to each child (which are based on the data and type of split during tabulation).} -\item{labels_var}{string, name of variable containing labels to be displayed -for the values of \code{var}} +\item{labels_var}{(\code{string})\cr name of variable containing labels to be displayed for the values of \code{var}.} -\item{cfun}{list/function/NULL. tabulation function(s) for creating content -rows. Must accept \code{x} or \code{df} as first parameter. Must accept -\code{labelstr} as the second argument. Can optionally accept all optional -arguments accepted by analysis functions. See \code{\link{analyze}}.} +\item{cfun}{(\code{list}, \code{function}, or \code{NULL})\cr tabulation function(s) for creating content rows. Must accept \code{x} +or \code{df} as first parameter. Must accept \code{labelstr} as the second argument. Can optionally accept all optional +arguments accepted by analysis functions. See \code{\link[=analyze]{analyze()}}.} -\item{cformat}{format spec. Format for content rows} +\item{cformat}{(\code{string}, \code{function}, or \code{list})\cr format for content rows.} -\item{cna_str}{character. NA string for use with \code{cformat} for content -table.} +\item{cna_str}{(\code{character})\cr NA string for use with \code{cformat} for content table.} -\item{split_fun}{function/NULL. custom splitting function See -\code{\link{custom_split_funs}}} +\item{split_fun}{(\code{function} or \code{NULL})\cr custom splitting function. See \link{custom_split_funs}.} -\item{split_format}{\code{FormatSpec}. Default format associated with the split -being created.} +\item{split_format}{(\code{string}, \code{function}, or \code{list})\cr default format associated with the split being created.} -\item{split_na_str}{character. NA string vector for use with \code{split_format}.} +\item{split_na_str}{(\code{character})\cr NA string vector for use with \code{split_format}.} -\item{valorder}{character vector. Order that the split children should appear -in resulting table.} +\item{valorder}{(\code{character})\cr the order that the split children should appear in resulting table.} -\item{split_name}{string. Name associated with this split (for pathing, etc)} +\item{split_name}{(\code{string})\cr name associated with the split (for pathing, etc.).} -\item{child_labels}{string. One of \code{"default"}, \code{"visible"}, -\code{"hidden"}. What should the display behavior be for the labels (i.e. -label rows) of the children of this split. Defaults to \code{"default"} -which flags the label row as visible only if the child has 0 content rows.} +\item{child_labels}{(\code{string})\cr the display behavior for the labels (i.e. label rows) of the children of this +split. Accepts \code{"default"}, \code{"visible"}, and \code{"hidden"}. Defaults to \code{"default"} which flags the label row as +visible only if the child has 0 content rows.} -\item{extra_args}{list. Extra arguments to be passed to the tabulation -function. Element position in the list corresponds to the children of this -split. Named elements in the child-specific lists are ignored if they do +\item{extra_args}{(\code{list})\cr extra arguments to be passed to the tabulation function. Element position in the list +corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do not match a formal argument of the tabulation function.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} -\item{label_pos}{character(1). Location the variable label should be -displayed, Accepts \code{"hidden"} (default for non-analyze row splits), \code{"visible"}, -\code{"topleft"}, and - for analyze splits only - \code{"default"}. For analyze calls, -\code{"default"} indicates that the variable should be visible if and only if -multiple variables are analyzed at the same level of nesting.} +\item{label_pos}{(\code{string})\cr location where the variable label should be displayed. Accepts \code{"hidden"} +(default for non-analyze row splits), \code{"visible"}, \code{"topleft"}, and \code{"default"} (for analyze splits only). For +\code{analyze} calls, \code{"default"} indicates that the variable should be visible if and only if multiple variables are +analyzed at the same level of nesting.} -\item{cindent_mod}{numeric(1). The indent modifier for the content tables -generated by this split.} +\item{cindent_mod}{(\code{numeric(1)})\cr the indent modifier for the content tables generated by this split.} -\item{cvar}{character(1). The variable, if any, which the content function -should accept. Defaults to NA.} +\item{cvar}{(\code{string})\cr the variable, if any, that the content function should accept. Defaults to \code{NA}.} -\item{cextra_args}{list. Extra arguments to be passed to the content function -when tabulating row group summaries.} +\item{cextra_args}{(\code{list})\cr extra arguments to be passed to the content function when tabulating row group +summaries.} -\item{page_prefix}{character(1). Prefix, to be appended with the split value, -when forcing pagination between the children of this split/table} +\item{page_prefix}{(\code{string})\cr prefix to be appended with the split value when forcing pagination between +the children of a split/table.} -\item{section_div}{character(1). String which should be repeated as a section -divider after each group defined by this split instruction, or -\code{NA_character_} (the default) for no section divider.} +\item{section_div}{(\code{string})\cr string which should be repeated as a section divider after each group defined +by this split instruction, or \code{NA_character_} (the default) for no section divider.} -\item{ref_group}{character. Value of \code{var} to be taken as the -ref_group/control to be compared against.} +\item{ref_group}{(\code{character})\cr value of \code{var} to be taken as the \code{ref_group}/control to be compared against.} -\item{label_fstr}{string. An \code{sprintf} style format string containing. For -non-comparison splits, it can contain up to one \code{"\%s"} which takes -the current split value and generates the row/column label. -Comparison-based splits it can contain up to two \code{"\%s"}.} +\item{label_fstr}{(\code{string})\cr a \code{sprintf} style format string. For non-comparison splits, it can contain up to +one \code{"\\\%s"} which takes the current split value and generates the row/column label. For comparison-based splits +it can contain up to two \code{"\\\%s"}.} } \value{ a \code{VarLevelSplit} object. diff --git a/man/Viewer.Rd b/man/Viewer.Rd index 92c892ba4..15f68f107 100644 --- a/man/Viewer.Rd +++ b/man/Viewer.Rd @@ -2,22 +2,22 @@ % Please edit documentation in R/Viewer.R \name{Viewer} \alias{Viewer} -\title{Display an \code{\link{rtable}} object in the Viewer pane in RStudio or in a browser} +\title{Display an \code{rtable} object in the Viewer pane in RStudio or in a browser} \usage{ Viewer(x, y = NULL, ...) } \arguments{ -\item{x}{object of class \code{rtable} or \code{shiny.tag} (defined in \code{htmltools} package)} +\item{x}{(\code{rtable} or \code{shiny.tag})\cr an object of class \code{rtable} or \code{shiny.tag} (defined in \code{htmltools} package).} -\item{y}{optional second argument of same type as \code{x}} +\item{y}{(\code{rtable} or \code{shiny.tag})\cr optional second argument of same type as \code{x}.} -\item{...}{arguments passed to \code{\link{as_html}}} +\item{...}{arguments passed to \code{\link[=as_html]{as_html()}}.} } \value{ -not meaningful. Called for the side effect of opening a browser or viewer pane. +Not meaningful. Called for the side effect of opening a browser or viewer pane. } \description{ -The table will be displayed using the bootstrap styling for tables. +The table will be displayed using bootstrap styling. } \examples{ if (interactive()) { diff --git a/man/add_colcounts.Rd b/man/add_colcounts.Rd index 9e4fd6c92..e6ae068f6 100644 --- a/man/add_colcounts.Rd +++ b/man/add_colcounts.Rd @@ -7,26 +7,23 @@ add_colcounts(lyt, format = "(N=xx)") } \arguments{ -\item{lyt}{layout object pre-data used for tabulation} +\item{lyt}{(\code{PreDataTableLayouts})\cr layout object pre-data used for tabulation.} -\item{format}{\code{FormatSpec}. Format associated with this split. Formats can be -declared via strings (\code{"xx.x"}) or function. In cases such as -\code{analyze} calls, they can character vectors or lists of functions.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr format associated with this split. Formats can be declared via +strings (\code{"xx.x"}) or function. In cases such as \code{analyze} calls, they can be character vectors or lists of +functions. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for a list of all available format strings.} } \value{ -A \code{PreDataTableLayouts} object suitable for passing to further -layouting functions, and to \code{build_table}. +A \code{PreDataTableLayouts} object suitable for passing to further layouting functions, and to \code{\link[=build_table]{build_table()}}. } \description{ Add the data derived column counts. } \details{ It is often the case that the the column counts derived from the -input data to \code{build_table} is not representative of the population counts. +input data to \code{\link[=build_table]{build_table()}} is not representative of the population counts. For example, if events are counted in the table and the header should -display the number of subjects and not the total number of events. In that -case use the \code{col_count} argument in \code{build_table} to control the counts -displayed in the table header. +display the number of subjects and not the total number of events. } \examples{ lyt <- basic_table() \%>\% diff --git a/man/add_combo_facet.Rd b/man/add_combo_facet.Rd index 9051bc157..9654fa13a 100644 --- a/man/add_combo_facet.Rd +++ b/man/add_combo_facet.Rd @@ -3,34 +3,31 @@ \name{add_combo_facet} \alias{add_combo_facet} \alias{add_overall_facet} -\title{Add a combination facet in postprocessing} +\title{Add a combination facet in post-processing} \usage{ add_combo_facet(name, label = name, levels, extra = list()) add_overall_facet(name, label, extra = list()) } \arguments{ -\item{name}{character(1). Name for the resulting facet (for use in pathing, etc).} +\item{name}{(\code{string})\cr name for the resulting facet (for use in pathing, etc.).} -\item{label}{character(1). Label for the resulting facet.} +\item{label}{(\code{string})\cr label for the resulting facet.} -\item{levels}{character. Vector of levels to combine within the resulting facet.} +\item{levels}{(\code{character})\cr vector of levels to combine within the resulting facet.} -\item{extra}{list. Extra arguments to be passed to analysis functions applied -within the resulting facet.} +\item{extra}{(\code{list})\cr extra arguments to be passed to analysis functions applied within the resulting facet.} } \value{ -a function which can be used within the \code{post} argument in -\code{make_split_fun}. +A function which can be used within the \code{post} argument in \code{\link[=make_split_fun]{make_split_fun()}}. } \description{ -Add a combination facet during postprocessing stage in a custom split fun. +Add a combination facet during the post-processing stage in a custom split fun. } \details{ -For \code{add_combo_facet}, the data associated with the resulting -facet will be the data associated with the facets for each level in -\code{levels}, \code{rbound} together. In particular, this means that if those levels -are overlapping, data that appears in both will be duplicated. +For \code{add_combo_facet}, the data associated with the resulting facet will be the data associated with the facets for +each level in \code{levels}, row-bound together. In particular, this means that if those levels are overlapping, data +that appears in both will be duplicated. } \examples{ mysplfun <- make_split_fun(post = list( @@ -49,7 +46,7 @@ tbl <- build_table(lyt, DM) } \seealso{ -\code{\link{make_split_fun}} +\code{\link[=make_split_fun]{make_split_fun()}} Other make_custom_split: \code{\link{drop_facet_levels}()}, diff --git a/man/add_combo_levels.Rd b/man/add_combo_levels.Rd index d5220512d..b64459c25 100644 --- a/man/add_combo_levels.Rd +++ b/man/add_combo_levels.Rd @@ -4,7 +4,7 @@ \name{select_all_levels} \alias{select_all_levels} \alias{add_combo_levels} -\title{Add Combination Levels to split} +\title{Add combination levels to split} \format{ An object of class \code{AllLevelsSentinel} of length 0. } @@ -14,30 +14,26 @@ select_all_levels add_combo_levels(combosdf, trim = FALSE, first = FALSE, keep_levels = NULL) } \arguments{ -\item{combosdf}{\code{data.frame}/\code{tbl_df}. Columns \code{valname}, \code{label}, \code{levelcombo}, -\code{exargs}. Of which \code{levelcombo} and \code{exargs} are list columns. Passing the -\code{select_all_levels} object as a value in the \code{comblevels} column -indicates that an overall/all-observations level should be created.} +\item{combosdf}{(\code{data.frame} or \code{tbl_df})\cr a data frame with columns \code{valname}, \code{label}, \code{levelcombo}, and +\code{exargs}. \code{levelcombo} and \code{exargs} should be list columns. Passing the \code{select_all_levels} object as a value in +\code{comblevels} column indicates that an overall/all-observations level should be created.} -\item{trim}{logical(1). Should splits corresponding with 0 observations be -kept when tabulating.} +\item{trim}{(\code{flag})\cr whether splits corresponding with 0 observations should be kept when tabulating.} -\item{first}{logical(1). Should the created split level be placed first in -the levels (\code{TRUE}) or last (\code{FALSE}, the default).} +\item{first}{(\code{flag})\cr whether the created split level should be placed first in the levels (\code{TRUE}) or +last (\code{FALSE}, the default).} -\item{keep_levels}{character or NULL. If non-NULL, the levels to retain -across both combination and individual levels.} +\item{keep_levels}{(\code{character} or \code{NULL})\cr if non-\code{NULL}, the levels to retain across both combination and +individual levels.} } \value{ -a closure suitable for use as a splitting function (\code{splfun}) -when creating a table layout +A closure suitable for use as a splitting function (\code{splfun}) when creating a table layout. } \description{ -Add Combination Levels to split +Add combination levels to split } \note{ -Analysis or summary functions for which the order matters should never -be used within the tabulation framework. +Analysis or summary functions for which the order matters should never be used within the tabulation framework. } \examples{ library(tibble) @@ -87,5 +83,6 @@ lyt3 <- basic_table(show_colcounts = TRUE) \%>\% tbl3 <- build_table(lyt3, smallerDM) tbl3 + } \keyword{datasets} diff --git a/man/add_existing_table.Rd b/man/add_existing_table.Rd index 34523eedb..d4612eb95 100644 --- a/man/add_existing_table.Rd +++ b/man/add_existing_table.Rd @@ -7,19 +7,16 @@ add_existing_table(lyt, tt, indent_mod = 0) } \arguments{ -\item{lyt}{layout object pre-data used for tabulation} +\item{lyt}{(\code{PreDataTableLayouts})\cr layout object pre-data used for tabulation.} -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} } \value{ -A \code{PreDataTableLayouts} object suitable for passing to further -layouting functions, and to \code{build_table}. +A \code{PreDataTableLayouts} object suitable for passing to further layouting functions, and to \code{\link[=build_table]{build_table()}}. } \description{ Add an already calculated table to the layout diff --git a/man/add_overall_col.Rd b/man/add_overall_col.Rd index de06e731a..ad107d0fb 100644 --- a/man/add_overall_col.Rd +++ b/man/add_overall_col.Rd @@ -2,26 +2,21 @@ % Please edit documentation in R/colby_constructors.R \name{add_overall_col} \alias{add_overall_col} -\title{Add Overall Column} +\title{Add overall column} \usage{ add_overall_col(lyt, label) } \arguments{ -\item{lyt}{layout object pre-data used for tabulation} +\item{lyt}{(\code{PreDataTableLayouts})\cr layout object pre-data used for tabulation.} -\item{label}{character(1). A label (not to be confused with the name) for the -object/structure.} +\item{label}{(\code{string})\cr a label (not to be confused with the name) for the object/structure.} } \value{ -A \code{PreDataTableLayouts} object suitable for passing to further -layouting functions, and to \code{build_table}. +A \code{PreDataTableLayouts} object suitable for passing to further layouting functions, and to \code{\link[=build_table]{build_table()}}. } \description{ -This function will \emph{only} add an overall -column at the \emph{top} level of splitting, NOT within -existing column splits. -See \code{\link{add_overall_level}} for the recommended -way to add overall columns more generally within existing splits. +This function will \emph{only} add an overall column at the \emph{top} level of splitting, NOT within existing column splits. +See \code{\link[=add_overall_level]{add_overall_level()}} for the recommended way to add overall columns more generally within existing splits. } \examples{ lyt <- basic_table() \%>\% diff --git a/man/add_overall_level.Rd b/man/add_overall_level.Rd index bd33f3d47..e9a6be544 100644 --- a/man/add_overall_level.Rd +++ b/man/add_overall_level.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/split_funs.R \name{add_overall_level} \alias{add_overall_level} -\title{Add an virtual 'overall' level to split} +\title{Add a virtual "overall" level to split} \usage{ add_overall_level( valname = "Overall", @@ -13,29 +13,25 @@ add_overall_level( ) } \arguments{ -\item{valname}{character(1). 'Value' to be assigned to the implicit -all-observations split level. Defaults to \code{"Overall"}} +\item{valname}{(\code{string})\cr value to be assigned to the implicit all-observations split level. Defaults to +\code{"Overall"}.} -\item{label}{character(1). A label (not to be confused with the name) for the -object/structure.} +\item{label}{(\code{string})\cr a label (not to be confused with the name) for the object/structure.} -\item{extra_args}{list. Extra arguments to be passed to the tabulation -function. Element position in the list corresponds to the children of this -split. Named elements in the child-specific lists are ignored if they do +\item{extra_args}{(\code{list})\cr extra arguments to be passed to the tabulation function. Element position in the list +corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do not match a formal argument of the tabulation function.} -\item{first}{logical(1). Should the implicit level appear first (\code{TRUE}) -or last \code{FALSE}. Defaults to \code{TRUE}.} +\item{first}{(\code{flag})\cr whether the implicit level should appear first (\code{TRUE}) or last (\code{FALSE}). Defaults +to \code{TRUE}.} -\item{trim}{logical(1). Should splits corresponding with 0 observations be -kept when tabulating.} +\item{trim}{(\code{flag})\cr whether splits corresponding with 0 observations should be kept when tabulating.} } \value{ -a closure suitable for use as a splitting function (\code{splfun}) -when creating a table layout +A closure suitable for use as a splitting function (\code{splfun}) when creating a table layout. } \description{ -Add an virtual 'overall' level to split +Add a virtual "overall" level to split } \examples{ lyt <- basic_table() \%>\% diff --git a/man/additional_fun_params.Rd b/man/additional_fun_params.Rd index 8d9cd0ef1..6a6f21bc8 100644 --- a/man/additional_fun_params.Rd +++ b/man/additional_fun_params.Rd @@ -2,60 +2,44 @@ % Please edit documentation in R/colby_constructors.R \name{additional_fun_params} \alias{additional_fun_params} -\title{Additional parameters within analysis and content functions -(\code{afun/cfun})} +\title{Additional parameters within analysis and content functions (\code{afun}/\code{cfun})} \description{ -It is possible to add specific parameters to \code{afun} and \code{cfun}, in \link{analyze} -and \link{summarize_row_groups} respectively. These parameters grant access to -relevant information like the row split structure (see \link{spl_context}) and the -predefined baseline (\code{.ref_group}). +It is possible to add specific parameters to \code{afun} and \code{cfun}, in \code{\link[=analyze]{analyze()}} and \code{\link[=summarize_row_groups]{summarize_row_groups()}}, +respectively. These parameters grant access to relevant information like the row split structure (see +\link{spl_context}) and the predefined baseline (\code{.ref_group}). } \details{ -We list and describe here all the parameters that can be added to a custom -analysis function: +We list and describe all the parameters that can be added to a custom analysis function below: \describe{ -\item{.N_col}{column-wise N (column count) for the full column being -tabulated within} -\item{.N_total}{overall N (all observation count, defined as sum of column -counts) for the tabulation} -\item{.N_row}{row-wise N (row group count) for the group of observations -being analyzed (i.e. with no column-based subsetting)} -\item{.df_row}{data.frame for observations in the row group being analyzed -(i.e. with no column-based subsetting)} -\item{.var}{variable that is analyzed} -\item{.ref_group}{data.frame or vector of subset corresponding to the -\code{ref_group} column including subsetting defined by row-splitting. -Optional and only required/meaningful if a \code{ref_group} column has been -defined} -\item{.ref_full}{data.frame or vector of subset corresponding to the -\code{ref_group} column without subsetting defined by row-splitting. Optional -and only required/meaningful if a \code{ref_group} column has been defined} -\item{.in_ref_col}{boolean indicates if calculation is done for cells -within the reference column} -\item{.spl_context}{data.frame, each row gives information about a -previous/'ancestor' split state. See \code{\link{spl_context}}} -\item{.alt_df_row}{data.frame, i.e. the \code{alt_count_df} after -row splitting. It can be used with \code{.all_col_exprs} and \code{.spl_context} -information to retrieve current faceting, but for \code{alt_count_df}. +\item{.N_col}{Column-wise N (column count) for the full column being tabulated within.} +\item{.N_total}{Overall N (all observation count, defined as sum of column counts) for the tabulation.} +\item{.N_row}{Row-wise N (row group count) for the group of observations being analyzed (i.e. with no +column-based subsetting).} +\item{.df_row}{\code{data.frame} for observations in the row group being analyzed (i.e. with no column-based +subsetting).} +\item{.var}{Variable being analyzed.} +\item{.ref_group}{\code{data.frame} or vector of subset corresponding to the \code{ref_group} column including subsetting +defined by row-splitting. Only required/meaningful if a \code{ref_group} column has been defined.} +\item{.ref_full}{\code{data.frame} or vector of subset corresponding to the \code{ref_group} column without subsetting +defined by row-splitting. Only required/meaningful if a \code{ref_group} column has been defined.} +\item{.in_ref_col}{Boolean indicating if calculation is done for cells within the reference column.} +\item{.spl_context}{\code{data.frame} where each row gives information about a previous 'ancestor' split state. +See \link{spl_context}.} +\item{.alt_df_row}{\code{data.frame}, i.e. the \code{alt_count_df} after row splitting. It can be used with +\code{.all_col_exprs} and \code{.spl_context} information to retrieve current faceting, but for \code{alt_count_df}. It can be an empty table if all the entries are filtered out.} -\item{.alt_df}{data.frame, \code{.alt_df_row} but filtered by columns expression. -This data present the same faceting of main data \code{df}. This also filters -\code{NAs} out if related parameters are set to (e.g. \code{inclNAs} in \link{analyze}). -Similarly to \code{.alt_df_row}, it can be an empty table if all the entries -are filtered out.} -\item{.all_col_exprs}{list of expressions. Each of them represents a -different column splitting.} -\item{.all_col_counts}{vector of integers. Each of them represents the global -count for each column. It differs if \code{alt_counts_df} is used -(see \link{build_table}).} +\item{.alt_df}{\code{data.frame}, \code{.alt_df_row} but filtered by columns expression. This data present the same +faceting of main data \code{df}. This also filters \code{NA}s out if related parameters are set to do so (e.g. \code{inclNAs} +in \code{\link[=analyze]{analyze()}}). Similarly to \code{.alt_df_row}, it can be an empty table if all the entries are filtered out.} +\item{.all_col_exprs}{List of expressions. Each of them represents a different column splitting.} +\item{.all_col_counts}{Vector of integers. Each of them represents the global count for each column. It differs +if \code{alt_counts_df} is used (see \code{\link[=build_table]{build_table()}}).} } } \note{ -If any of these formals is specified incorrectly or not -present in the tabulation machinery, it will be as if missing. For -example\code{.ref_group} will be missing if no baseline is previously defined -during data splitting (via \code{ref_group} parameters in, e.g., \link{split_rows_by}). -Similarly, if no \code{alt_counts_df} is provided into \link{build_table}, -\code{.alt_df_row} and \code{.alt_df} will not be present. +If any of these formals is specified incorrectly or not present in the tabulation machinery, it will be +treated as if missing. For example, \code{.ref_group} will be missing if no baseline is previously defined during +data splitting (via \code{ref_group} parameters in, e.g., \code{\link[=split_rows_by]{split_rows_by()}}). Similarly, if no \code{alt_counts_df} is +provided to \code{\link[=build_table]{build_table()}}, \code{.alt_df_row} and \code{.alt_df} will not be present. } diff --git a/man/analyze.Rd b/man/analyze.Rd index f631a2b2d..f5d174195 100644 --- a/man/analyze.Rd +++ b/man/analyze.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/colby_constructors.R \name{analyze} \alias{analyze} -\title{Generate Rows Analyzing Variables Across Columns} +\title{Generate rows analyzing variables across columns} \usage{ analyze( lyt, @@ -21,103 +21,75 @@ analyze( ) } \arguments{ -\item{lyt}{layout object pre-data used for tabulation} +\item{lyt}{(\code{PreDataTableLayouts})\cr layout object pre-data used for tabulation.} -\item{vars}{character vector. Multiple variable names.} +\item{vars}{(\code{character})\cr vector of variable names.} -\item{afun}{function. Analysis function, must take \code{x} or \code{df} as -its first parameter. Can optionally take other parameters which will be -populated by the tabulation framework. See Details in -\code{\link{analyze}}.} +\item{afun}{(\code{function})\cr analysis function. Must accept \code{x} or \code{df} as its first parameter. Can optionally take +other parameters which will be populated by the tabulation framework. See Details in \code{\link[=analyze]{analyze()}}.} -\item{var_labels}{character. Variable labels for 1 or more variables} +\item{var_labels}{(\code{character})\cr vector of labels for one or more variables.} -\item{table_names}{character. Names for the tables representing each atomic -analysis. Defaults to \code{var}.} +\item{table_names}{(\code{character})\cr names for the tables representing each atomic analysis. Defaults to \code{var}.} -\item{format}{\code{FormatSpec}. Format associated with this split. Formats can be -declared via strings (\code{"xx.x"}) or function. In cases such as -\code{analyze} calls, they can character vectors or lists of functions.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr format associated with this split. Formats can be declared via +strings (\code{"xx.x"}) or function. In cases such as \code{analyze} calls, they can be character vectors or lists of +functions. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for a list of all available format strings.} -\item{na_str}{character(1). String that should be displayed when the value of \code{x} is missing. -Defaults to \code{"NA"}.} +\item{na_str}{(\code{string})\cr string that should be displayed when the value of \code{x} is missing. Defaults to \code{"NA"}.} -\item{nested}{boolean. Should this layout instruction be applied within the -existing layout structure \emph{if possible} (\code{TRUE}, the default) or as a -new top-level element (`FALSE). Ignored if it would nest a split underneath -analyses, which is not allowed.} +\item{nested}{(\code{logical})\cr whether this layout instruction should be applied within the existing layout structure +\emph{if possible} (\code{TRUE}, the default) or as a new top-level element (\code{FALSE}). Ignored if it would nest a split +underneath analyses, which is not allowed.} -\item{inclNAs}{boolean. Should observations with NA in the \code{var} -variable(s) be included when performing this analysis. Defaults to -\code{FALSE}} +\item{inclNAs}{(\code{logical})\cr whether NA observations in the \code{var} variable(s) should be included when performing +the analysis. Defaults to \code{FALSE}.} -\item{extra_args}{list. Extra arguments to be passed to the tabulation -function. Element position in the list corresponds to the children of this -split. Named elements in the child-specific lists are ignored if they do +\item{extra_args}{(\code{list})\cr extra arguments to be passed to the tabulation function. Element position in the list +corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do not match a formal argument of the tabulation function.} -\item{show_labels}{character(1). Should the variable labels for corresponding -to the variable(s) in \code{vars} be visible in the resulting table.} +\item{show_labels}{(\code{string})\cr whether the variable labels corresponding to the variable(s) in \code{vars} +should be visible in the resulting table.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} -\item{section_div}{character(1). String which should be repeated as a section -divider after each group defined by this split instruction, or -\code{NA_character_} (the default) for no section divider.} +\item{section_div}{(\code{string})\cr string which should be repeated as a section divider after each group defined +by this split instruction, or \code{NA_character_} (the default) for no section divider.} } \value{ -A \code{PreDataTableLayouts} object suitable for passing to further -layouting functions, and to \code{build_table}. +A \code{PreDataTableLayouts} object suitable for passing to further layouting functions, and to \code{\link[=build_table]{build_table()}}. } \description{ -Adding \emph{analyzed variables} to our table layout defines the primary -tabulation to be performed. We do this by adding calls to \code{analyze} -and/or \code{\link{analyze_colvars}} into our layout pipeline. As with adding -further splitting, the tabulation will occur at the current/next level of -nesting by default. +Adding \emph{analyzed variables} to our table layout defines the primary tabulation to be performed. We do this by +adding calls to \code{analyze} and/or \code{\link[=analyze_colvars]{analyze_colvars()}} into our layout pipeline. As with adding further splitting, +the tabulation will occur at the current/next level of nesting by default. } \details{ -When non-NULL \code{format} is used to specify formats for all generated -rows, and can be a character vector, a function, or a list of functions. It -will be repped out to the number of rows once this is known during the -tabulation process, but will be overridden by formats specified within -\code{rcell} calls in \code{afun}. - -The analysis function (\code{afun}) should take as its first parameter either -\code{x} or \code{df}. Which of these the function accepts changes the -behavior when tabulation is performed. +When non-\code{NULL}, \code{format} is used to specify formats for all generated rows, and can be a character vector, a +function, or a list of functions. It will be repped out to the number of rows once this is calculated during the +tabulation process, but will be overridden by formats specified within \code{rcell} calls in \code{afun}. +The analysis function (\code{afun}) should take as its first parameter either \code{x} or \code{df}. Whichever of these the +function accepts will change the behavior when tabulation is performed as follows: \itemize{ -\item{ -If \code{afun}'s first parameter is x, it will receive the corresponding -subset \emph{vector} of data from the relevant column (from \code{var} -here) of the raw data being used to build the table. -} - -\item{ -If \code{afun}'s first parameter is \code{df}, it will receive the -corresponding subset \emph{data.frame} (i.e. all columns) of the raw data -being tabulated -} +\item If \code{afun}'s first parameter is \code{x}, it will receive the corresponding subset \emph{vector} of data from the relevant +column (from \code{var} here) of the raw data being used to build the table. +\item If \code{afun}'s first parameter is \code{df}, it will receive the corresponding subset \emph{data frame} (i.e. all columns) of +the raw data being tabulated. } -In addition to differentiation on the first argument, the analysis function -can optionally accept a number of other parameters which, \emph{if and only -if} present in the formals will be passed to the function by the tabulation -machinery. These are listed and described in \code{\link{additional_fun_params}}. +In addition to differentiation on the first argument, the analysis function can optionally accept a number of +other parameters which, \emph{if and only if} present in the formals, will be passed to the function by the tabulation +machinery. These are listed and described in \link{additional_fun_params}. } \note{ -None of the arguments described in the Details section -can be overridden via \code{extra_args} or when calling -\code{\link{make_afun}}. \code{.N_col} and \code{.N_total} can -be overridden via the \code{col_counts} argument to -\code{\link{build_table}}. Alternative values for the others -must be calculated within \code{afun} based on a combination -of extra arguments and the unmodified values provided by the -tabulation framework. +None of the arguments described in the Details section can be overridden via \code{extra_args} or when calling +\code{\link[=make_afun]{make_afun()}}. \code{.N_col} and \code{.N_total} can be overridden via the \code{col_counts} argument to \code{\link[=build_table]{build_table()}}. +Alternative values for the others must be calculated within \code{afun} based on a combination of extra arguments and +the unmodified values provided by the tabulation framework. } \examples{ lyt <- basic_table() \%>\% diff --git a/man/analyze_colvars.Rd b/man/analyze_colvars.Rd index bb5025383..70a3bf65b 100644 --- a/man/analyze_colvars.Rd +++ b/man/analyze_colvars.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/colby_constructors.R \name{analyze_colvars} \alias{analyze_colvars} -\title{Generate Rows Analyzing Different Variables Across Columns} +\title{Generate rows analyzing different variables across columns} \usage{ analyze_colvars( lyt, @@ -16,49 +16,43 @@ analyze_colvars( ) } \arguments{ -\item{lyt}{layout object pre-data used for tabulation} +\item{lyt}{(\code{PreDataTableLayouts})\cr layout object pre-data used for tabulation.} -\item{afun}{function or list. Function(s) to be used to calculate the values -in each column. The list will be repped out as needed and matched by -position with the columns during tabulation. This functions accepts the same -parameters as \link{analyze} like \code{afun} and \code{format}. For further information see -\code{\link{additional_fun_params}}.} +\item{afun}{(\code{function} or \code{list})\cr function(s) to be used to calculate the values in each column. The list +will be repped out as needed and matched by position with the columns during tabulation. This functions +accepts the same parameters as \code{\link[=analyze]{analyze()}} like \code{afun} and \code{format}. For further information see +\link{additional_fun_params}.} -\item{format}{\code{FormatSpec}. Format associated with this split. Formats can be -declared via strings (\code{"xx.x"}) or function. In cases such as -\code{analyze} calls, they can character vectors or lists of functions.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr format associated with this split. Formats can be declared via +strings (\code{"xx.x"}) or function. In cases such as \code{analyze} calls, they can be character vectors or lists of +functions. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for a list of all available format strings.} -\item{na_str}{character(1). String that should be displayed when the value of \code{x} is missing. -Defaults to \code{"NA"}.} +\item{na_str}{(\code{string})\cr string that should be displayed when the value of \code{x} is missing. Defaults to \code{"NA"}.} -\item{nested}{boolean. Should this layout instruction be applied within the -existing layout structure \emph{if possible} (\code{TRUE}, the default) or as a -new top-level element (`FALSE). Ignored if it would nest a split underneath -analyses, which is not allowed.} +\item{nested}{(\code{logical})\cr whether this layout instruction should be applied within the existing layout structure +\emph{if possible} (\code{TRUE}, the default) or as a new top-level element (\code{FALSE}). Ignored if it would nest a split +underneath analyses, which is not allowed.} -\item{extra_args}{list. Extra arguments to be passed to the tabulation -function. Element position in the list corresponds to the children of this -split. Named elements in the child-specific lists are ignored if they do +\item{extra_args}{(\code{list})\cr extra arguments to be passed to the tabulation function. Element position in the list +corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do not match a formal argument of the tabulation function.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} -\item{inclNAs}{boolean. Should observations with NA in the \code{var} -variable(s) be included when performing this analysis. Defaults to -\code{FALSE}} +\item{inclNAs}{(\code{logical})\cr whether NA observations in the \code{var} variable(s) should be included when performing +the analysis. Defaults to \code{FALSE}.} } \value{ -A \code{PreDataTableLayouts} object suitable for passing to further -layouting functions, and to \code{build_table}. +A \code{PreDataTableLayouts} object suitable for passing to further layouting functions, and to \code{\link[=build_table]{build_table()}}. } \description{ -Generate Rows Analyzing Different Variables Across Columns +Generate rows analyzing different variables across columns } \examples{ library(dplyr) + ANL <- DM \%>\% mutate(value = rnorm(n()), pctdiff = runif(n())) ## toy example where we take the mean of the first variable and the diff --git a/man/append_topleft.Rd b/man/append_topleft.Rd index fad30eefd..4b57764b6 100644 --- a/man/append_topleft.Rd +++ b/man/append_topleft.Rd @@ -7,34 +7,28 @@ append_topleft(lyt, newlines) } \arguments{ -\item{lyt}{layout object pre-data used for tabulation} +\item{lyt}{(\code{PreDataTableLayouts})\cr layout object pre-data used for tabulation.} -\item{newlines}{character. The new line(s) to be added to the materials} +\item{newlines}{(\code{character})\cr the new line(s) to be added to the materials.} } \value{ -A \code{PreDataTableLayouts} object suitable for passing to further -layouting functions, and to \code{build_table}. +A \code{PreDataTableLayouts} object suitable for passing to further layouting functions, and to \code{\link[=build_table]{build_table()}}. } \description{ -This function \emph{adds} \code{newlines} to the current -set of "top-left materials". +This function \emph{adds} \code{newlines} to the current set of "top-left materials". } \details{ -Adds \code{newlines} to the set of strings representing the 'top-left' -materials declared in the layout (the content displayed to the left of -the column labels when the resulting tables are printed). +Adds \code{newlines} to the set of strings representing the 'top-left' materials declared in the layout (the content +displayed to the left of the column labels when the resulting tables are printed). -Top-left material strings are stored and then displayed \emph{exactly as is}, -no structure or indenting is applied to them either when they are added -or when they are displayed. +Top-left material strings are stored and then displayed \emph{exactly as is}, no structure or indenting is applied to +them either when they are added or when they are displayed. } \note{ -Currently, where in the construction of the layout this is called -makes no difference, as it is independent of the actual splitting keywords. -This may change in the future. +Currently, where in the construction of the layout this is called makes no difference, as it is independent of +the actual splitting keywords. This may change in the future. -This function is experimental, its name and the details of -its behavior are subject to change in future versions. +This function is experimental, its name and the details of its behavior are subject to change in future versions. } \examples{ library(dplyr) diff --git a/man/as_html.Rd b/man/as_html.Rd index 5b6a4dead..deb4b1c17 100644 --- a/man/as_html.Rd +++ b/man/as_html.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/as_html.R \name{as_html} \alias{as_html} -\title{Convert an \code{rtable} object to a \code{shiny.tag} html object} +\title{Convert an \code{rtable} object to a \code{shiny.tag} HTML object} \usage{ as_html( x, @@ -17,33 +17,34 @@ as_html( ) } \arguments{ -\item{x}{\code{rtable} object} +\item{x}{(\code{VTableTree})\cr a \code{TableTree} object.} -\item{width}{a string to indicate the desired width of the table. Common input formats include a -percentage of the viewer window width (e.g. \code{"100\%"}) or a distance value (e.g. \code{"300px"}). -Defaults to \code{NULL}.} +\item{width}{(\code{character})\cr a string to indicate the desired width of the table. Common input formats include a +percentage of the viewer window width (e.g. \code{"100\%"}) or a distance value (e.g. \code{"300px"}). Defaults to \code{NULL}.} -\item{class_table}{class for \code{table} tag} +\item{class_table}{(\code{character})\cr class for \code{table} tag.} -\item{class_tr}{class for \code{tr} tag} +\item{class_tr}{(\code{character})\cr class for \code{tr} tag.} -\item{class_th}{class for \code{th} tag} +\item{class_th}{(\code{character})\cr class for \code{th} tag.} -\item{link_label}{link anchor label (not including \verb{tab:} prefix) for the table.} +\item{link_label}{(\code{character})\cr link anchor label (not including \verb{tab:} prefix) for the table.} -\item{bold}{elements in table output that should be bold. Options are \code{"main_title"}, \code{"subtitles"}, -\code{"header"}, \code{"row_names"}, \code{"label_rows"}, and \code{"content_rows"} (which includes any non-label rows). -Defaults to \code{"header"}.} +\item{bold}{(\code{character})\cr elements in table output that should be bold. Options are \code{"main_title"}, +\code{"subtitles"}, \code{"header"}, \code{"row_names"}, \code{"label_rows"}, and \code{"content_rows"} (which includes any non-label +rows). Defaults to \code{"header"}.} -\item{header_sep_line}{whether a black line should be printed to under the table header. Defaults to \code{TRUE}.} +\item{header_sep_line}{(\code{flag})\cr whether a black line should be printed to under the table header. Defaults +to \code{TRUE}.} -\item{no_spaces_between_cells}{whether spaces between table cells should be collapsed. Defaults to \code{FALSE}.} +\item{no_spaces_between_cells}{(\code{flag})\cr whether spaces between table cells should be collapsed. Defaults +to \code{FALSE}.} } \value{ A \code{shiny.tag} object representing \code{x} in HTML. } \description{ -The returned \code{html} object can be immediately used in \code{shiny} and \code{rmarkdown}. +The returned HTML object can be immediately used in \code{shiny} and \code{rmarkdown}. } \examples{ tbl <- rtable( diff --git a/man/asvec.Rd b/man/asvec.Rd index 9c6546511..d930e6f60 100644 --- a/man/asvec.Rd +++ b/man/asvec.Rd @@ -3,21 +3,21 @@ \name{asvec} \alias{asvec} \alias{as.vector,VTableTree-method} -\title{convert to a vector} +\title{Convert to a vector} \usage{ \S4method{as.vector}{VTableTree}(x, mode = "any") } \arguments{ -\item{x}{ANY. The object to be converted to a vector} +\item{x}{(\code{ANY})\cr the object to be converted to a vector.} -\item{mode}{character(1). Passed on to \code{\link[base]{as.vector}}} +\item{mode}{(\code{string})\cr passed on to \code{\link[=as.vector]{as.vector()}}.} } \value{ -a vector of the chosen mode (or an error is raised if more than one row was present). +A vector of the chosen mode (or an error is raised if more than one row was present). } \description{ -Convert an \code{rtables} framework object into a vector, if possible. -This is unlikely to be useful in realistic scenarios. +Convert an \code{rtables} framework object into a vector, if possible. This is unlikely to be useful in +realistic scenarios. } \note{ This only works for a table with a single row or a row object. diff --git a/man/avarspl.Rd b/man/avarspl.Rd index 53c66e6af..99cde0194 100644 --- a/man/avarspl.Rd +++ b/man/avarspl.Rd @@ -61,70 +61,57 @@ AnalyzeMultiVars( ) } \arguments{ -\item{var}{string, variable name} +\item{var}{(\code{string})\cr variable name.} -\item{split_label}{string. Label string to be associated with the table -generated by the split. Not to be confused with labels assigned to each -child (which are based on the data and type of split during tabulation).} +\item{split_label}{(\code{string})\cr label to be associated with the table generated by the split. Not to be confused +with labels assigned to each child (which are based on the data and type of split during tabulation).} -\item{afun}{function. Analysis function, must take \code{x} or \code{df} as -its first parameter. Can optionally take other parameters which will be -populated by the tabulation framework. See Details in -\code{\link{analyze}}.} +\item{afun}{(\code{function})\cr analysis function. Must accept \code{x} or \code{df} as its first parameter. Can optionally take +other parameters which will be populated by the tabulation framework. See Details in \code{\link[=analyze]{analyze()}}.} -\item{defrowlab}{character. Default row labels if they are not specified by -the return value of \code{afun}} +\item{defrowlab}{(\code{character})\cr default row labels, if not specified by the return value of \code{afun}.} -\item{cfun}{list/function/NULL. tabulation function(s) for creating content -rows. Must accept \code{x} or \code{df} as first parameter. Must accept -\code{labelstr} as the second argument. Can optionally accept all optional -arguments accepted by analysis functions. See \code{\link{analyze}}.} +\item{cfun}{(\code{list}, \code{function}, or \code{NULL})\cr tabulation function(s) for creating content rows. Must accept \code{x} +or \code{df} as first parameter. Must accept \code{labelstr} as the second argument. Can optionally accept all optional +arguments accepted by analysis functions. See \code{\link[=analyze]{analyze()}}.} -\item{cformat}{format spec. Format for content rows} +\item{cformat}{(\code{string}, \code{function}, or \code{list})\cr format for content rows.} -\item{split_format}{\code{FormatSpec}. Default format associated with the split -being created.} +\item{split_format}{(\code{string}, \code{function}, or \code{list})\cr default format associated with the split being created.} -\item{split_na_str}{character. NA string vector for use with \code{split_format}.} +\item{split_na_str}{(\code{character})\cr NA string vector for use with \code{split_format}.} -\item{inclNAs}{boolean. Should observations with NA in the \code{var} -variable(s) be included when performing this analysis. Defaults to -\code{FALSE}} +\item{inclNAs}{(\code{logical})\cr whether NA observations in the \code{var} variable(s) should be included when performing +the analysis. Defaults to \code{FALSE}.} -\item{split_name}{string. Name associated with this split (for pathing, etc)} +\item{split_name}{(\code{string})\cr name associated with the split (for pathing, etc.).} -\item{extra_args}{list. Extra arguments to be passed to the tabulation -function. Element position in the list corresponds to the children of this -split. Named elements in the child-specific lists are ignored if they do +\item{extra_args}{(\code{list})\cr extra arguments to be passed to the tabulation function. Element position in the list +corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do not match a formal argument of the tabulation function.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} -\item{label_pos}{character(1). Location the variable label should be -displayed, Accepts \code{"hidden"} (default for non-analyze row splits), \code{"visible"}, -\code{"topleft"}, and - for analyze splits only - \code{"default"}. For analyze calls, -\code{"default"} indicates that the variable should be visible if and only if -multiple variables are analyzed at the same level of nesting.} +\item{label_pos}{(\code{string})\cr location where the variable label should be displayed. Accepts \code{"hidden"} +(default for non-analyze row splits), \code{"visible"}, \code{"topleft"}, and \code{"default"} (for analyze splits only). For +\code{analyze} calls, \code{"default"} indicates that the variable should be visible if and only if multiple variables are +analyzed at the same level of nesting.} -\item{cvar}{character(1). The variable, if any, which the content function -should accept. Defaults to NA.} +\item{cvar}{(\code{string})\cr the variable, if any, that the content function should accept. Defaults to \code{NA}.} -\item{section_div}{character(1). String which should be repeated as a section -divider after each group defined by this split instruction, or -\code{NA_character_} (the default) for no section divider.} +\item{section_div}{(\code{string})\cr string which should be repeated as a section divider after each group defined +by this split instruction, or \code{NA_character_} (the default) for no section divider.} -\item{.payload}{Used internally, not intended to be set by end users.} +\item{.payload}{(\code{list})\cr used internally, not intended to be set by end users.} -\item{child_labels}{string. One of \code{"default"}, \code{"visible"}, -\code{"hidden"}. What should the display behavior be for the labels (i.e. -label rows) of the children of this split. Defaults to \code{"default"} -which flags the label row as visible only if the child has 0 content rows.} +\item{child_labels}{(\code{string})\cr the display behavior for the labels (i.e. label rows) of the children of this +split. Accepts \code{"default"}, \code{"visible"}, and \code{"hidden"}. Defaults to \code{"default"} which flags the label row as +visible only if the child has 0 content rows.} -\item{child_names}{character. Names to be given to the sub splits contained -by a compound split (typically a \code{AnalyzeMultiVars} split object).} +\item{child_names}{(\code{character})\cr names to be given to the subsplits contained by a compound split (typically +an \code{AnalyzeMultiVars} split object).} } \value{ An \code{AnalyzeVarSplit} object. diff --git a/man/basic_table.Rd b/man/basic_table.Rd index a7c8ce462..2b087b5a4 100644 --- a/man/basic_table.Rd +++ b/man/basic_table.Rd @@ -17,67 +17,55 @@ basic_table( ) } \arguments{ -\item{title}{character(1). Main title (\code{\link[=main_title]{main_title()}}) is a single string. -Ignored for subtables.} +\item{title}{(\code{string})\cr single string to use as main title (\code{\link[=main_title]{main_title()}}). Ignored for subtables.} -\item{subtitles}{character. Subtitles (\code{\link[=subtitles]{subtitles()}}) can be vector of strings, where -every element is printed in a separate line. Ignored for subtables.} +\item{subtitles}{(\code{character})\cr a vector of strings to use as subtitles (\code{\link[=subtitles]{subtitles()}}), where every element is +printed on a separate line. Ignored for subtables.} -\item{main_footer}{character. Main global (non-referential) footer materials -(\code{\link[=main_footer]{main_footer()}}). If it is a vector of strings, they will be printed on separate -lines.} +\item{main_footer}{(\code{character})\cr a vector of strings to use as main global (non-referential) footer materials +(\code{\link[=main_footer]{main_footer()}}), where every element is printed on a separate line.} -\item{prov_footer}{character. Provenance-related global footer materials -(\code{\link[=prov_footer]{prov_footer()}}). It can be also a vector of strings, printed on different lines. -Generally should not be modified by hand.} +\item{prov_footer}{(\code{character})\cr a vector of strings to use as provenance-related global footer materials +(\code{\link[=prov_footer]{prov_footer()}}), where every element is printed on a separate line.} -\item{show_colcounts}{logical(1). Should column counts be displayed in the -resulting table when this layout is applied to data} +\item{show_colcounts}{(\code{flag})\cr whether column counts should be displayed in the resulting table when this +layout is applied to data.} -\item{colcount_format}{character(1). Format for use when displaying the -column counts. Must be 1d, or 2d where one component is a percent. See -details.} +\item{colcount_format}{(\code{string})\cr format for use when displaying the column counts. Must be 1d, or 2d +where one component is a percent. See Details below.} -\item{header_section_div}{character(1). String which will be used to divide the header -from the table. See \code{\link[=header_section_div]{header_section_div()}} for getter and setter of these. -Please consider changing last element of \code{\link[=section_div]{section_div()}} when concatenating -tables that need a divider between them.} +\item{header_section_div}{(\code{string})\cr string which will be used to divide the header from the table. See +\code{\link[=header_section_div]{header_section_div()}} for the associated getter and setter. Please consider changing last element of +\code{\link[=section_div]{section_div()}} when concatenating tables that require a divider between them.} -\item{top_level_section_div}{character(1). If assigned to a single character, -the first (top level) split or division of the table will be highlighted by a line made of that character. -See \link{section_div} for more information.} +\item{top_level_section_div}{(\code{character(1)})\cr if assigned a single character, the first (top level) split +or division of the table will be highlighted by a line made of that character. See \link{section_div} for more +information.} -\item{inset}{numeric(1). Number of spaces to inset the table header, table -body, referential footnotes, and main_footer, as compared to alignment -of title, subtitle, and provenance footer. Defaults to 0 (no inset).} +\item{inset}{(\code{numeric(1)})\cr number of spaces to inset the table header, table body, referential footnotes, and +main_footer, as compared to alignment of title, subtitle, and provenance footer. Defaults to 0 (no inset).} } \value{ -A \code{PreDataTableLayouts} object suitable for passing to further -layouting functions, and to \code{build_table}. +A \code{PreDataTableLayouts} object suitable for passing to further layouting functions, and to \code{\link[=build_table]{build_table()}}. } \description{ Every layout must start with a basic table. } \details{ -\code{colcount_format} is ignored if \code{show_colcounts} is \code{FALSE} (the default). -When \code{show_colcounts} is \code{TRUE}, and \code{colcount_format} is 2-dimensional with -a percent component, the value component for the percent is always populated -with \code{1} (i.e. 100\%). 1d formats are used to render the counts exactly as they -normally would be, while 2d formats which don't include a percent, and all 3d -formats result in an error. Formats in the form of functions are not supported for -\code{colcount} format. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for -the list of valid format labels to select from. +\code{colcount_format} is ignored if \code{show_colcounts} is \code{FALSE} (the default). When \code{show_colcounts} is \code{TRUE}, +and \code{colcount_format} is 2-dimensional with a percent component, the value component for the percent is always +populated with \code{1} (i.e. 100\%). 1d formats are used to render the counts exactly as they normally would be, +while 2d formats which don't include a percent, and all 3d formats result in an error. Formats in the form of +functions are not supported for \code{colcount} format. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for the list +of valid format labels to select from. } \note{ \itemize{ -\item Because percent components in \code{colcount_format} are \emph{always} -populated with the value 1, we can get arguably strange results, such as -that individual arm columns and a combined "all patients" column all -list "100\%" as their percentage, even though the individual arm columns -represent strict subsets of the all patients column. -\item Note that subtitles (\code{\link[=subtitles]{subtitles()}}) and footers (\code{\link[=main_footer]{main_footer()}} and \code{\link[=prov_footer]{prov_footer()}}) -that spans more than one line can be supplied as a character vector to maintain -indentation on multiple lines. +\item Because percent components in \code{colcount_format} are \emph{always} populated with the value 1, we can get arguably +strange results, such as that individual arm columns and a combined "all patients" column all list "100\%" as +their percentage, even though the individual arm columns represent strict subsets of the "all patients" column. +\item Note that subtitles (\code{\link[=subtitles]{subtitles()}}) and footers (\code{\link[=main_footer]{main_footer()}} and \code{\link[=prov_footer]{prov_footer()}}) that span more than one +line can be supplied as a character vector to maintain indentation on multiple lines. } } \examples{ diff --git a/man/brackets.Rd b/man/brackets.Rd index 1453ce8b0..6426ccf95 100644 --- a/man/brackets.Rd +++ b/man/brackets.Rd @@ -11,52 +11,46 @@ \S4method{[}{VTableTree,logical,logical}(x, i, j, ..., drop = FALSE) } \arguments{ -\item{x}{\code{TableTree}} +\item{x}{(\code{TableTree})\cr a \code{TableTree} object.} -\item{i}{index} +\item{i}{(\code{numeric(1)})\cr index.} -\item{j}{index} +\item{j}{(\code{numeric(1)})\cr index.} -\item{\dots}{Includes +\item{...}{additional arguments. Includes: \describe{ -\item{\emph{keep_topleft}}{logical(1) (\code{[} only) Should the \code{top-left} -material for the table be retained after subsetting. Defaults to \code{TRUE} if -all rows are included (i.e. subsetting was by column), and drops it otherwise.} -\item{\emph{keep_titles}}{logical(1) Should title information be retained. Defaults to \code{FALSE}.} -\item{\emph{keep_footers}}{logical(1) Should non-referential footer -information be retained. Defaults to \code{keep_titles}.} -\item{\emph{reindex_refs}}{logical(1). Should referential footnotes be -re-indexed as if the resulting subset is the entire table. Defaults to -\code{TRUE}.} +\item{\code{keep_topleft}}{(\code{flag}) (\code{[} only) whether the top-left material for the table should be retained after +subsetting. Defaults to \code{TRUE} if all rows are included (i.e. subsetting was by column), and drops it +otherwise.} +\item{\code{keep_titles}}{(\code{flag}) whether title information should be retained. Defaults to \code{FALSE}.} +\item{\code{keep_footers}}{(\code{flag}) whether non-referential footer information should be retained. Defaults to +\code{keep_titles}.} +\item{\code{reindex_refs}}{(\code{flag}) whether referential footnotes should be re-indexed as if the resulting subset is +the entire table. Defaults to \code{TRUE}.} }} -\item{value}{Replacement value (list, \code{TableRow}, or \code{TableTree})} +\item{value}{(\code{list}, \code{TableRow}, or \code{TableTree})\cr replacement value.} -\item{drop}{logical(1). Should the value in the cell be returned if one -cell is selected by the combination of \code{i} and \code{j}. It is not possible -to return a vector of values. To do so please consider using \code{\link[=cell_values]{cell_values()}}. -Defaults to \code{FALSE}.} +\item{drop}{(\code{flag})\cr whether the value in the cell should be returned if one cell is selected by the +combination of \code{i} and \code{j}. It is not possible to return a vector of values. To do so please consider using +\code{\link[=cell_values]{cell_values()}}. Defaults to \code{FALSE}.} } \value{ -a \code{TableTree} (or \code{ElementaryTable}) object, unless a -single cell was selected with \code{drop=TRUE}, in which case the (possibly -multi-valued) fully stripped raw value of the selected cell. +A \code{TableTree} (or \code{ElementaryTable}) object, unless a single cell was selected with \code{drop = TRUE}, in which +case the (possibly multi-valued) fully stripped raw value of the selected cell. } \description{ Retrieve and assign elements of a \code{TableTree} } \details{ -by default, subsetting drops the information about title, subtitle, -main footer, provenance footer, and \code{topleft}. If only a column is selected -and all rows are kept, the \code{topleft} information remains as default. Any -referential footnote is kept whenever the subset table contains the -referenced element. +By default, subsetting drops the information about title, subtitle, main footer, provenance footer, and \code{topleft}. +If only a column is selected and all rows are kept, the \code{topleft} information remains as default. Any referential +footnote is kept whenever the subset table contains the referenced element. } \note{ -subsetting always preserve the original order, even if provided -indexes do not preserve it. If sorting is needed, please consider -using \code{sort_at_path()}. Also note that \code{character} indices are treated as paths, -not vectors of names in both \code{[} and \verb{[<-}. +Subsetting always preserve the original order, even if provided indexes do not preserve it. If sorting is needed, +please consider using \code{sort_at_path()}. Also note that \code{character} indices are treated as paths, not vectors of +names in both \code{[} and \verb{[<-}. } \examples{ lyt <- basic_table( @@ -129,6 +123,8 @@ tbl[c(4, 3, 1), c(3, 1)] # It preserves order and wanted selection } \seealso{ -Regarding sorting: \code{sort_at_path()} and how to understand path -structure: \code{summarize_row_groups()}, and \code{summarize_col_groups()}. +\itemize{ +\item \code{\link[=sort_at_path]{sort_at_path()}} to understand sorting. +\item \code{\link[=summarize_row_groups]{summarize_row_groups()}} to understand path structure. +} } diff --git a/man/build_table.Rd b/man/build_table.Rd index 31c83fa1f..37869f8b0 100644 --- a/man/build_table.Rd +++ b/man/build_table.Rd @@ -16,59 +16,49 @@ build_table( ) } \arguments{ -\item{lyt}{layout object pre-data used for tabulation} +\item{lyt}{(\code{PreDataTableLayouts})\cr layout object pre-data used for tabulation.} -\item{df}{dataset (\code{data.frame} or \code{tibble})} +\item{df}{(\code{data.frame} or \code{tibble})\cr dataset.} -\item{alt_counts_df}{dataset (\code{data.frame} or \code{tibble}). Alternative full data -the rtables framework will use (\emph{only}) when calculating column -counts.} +\item{alt_counts_df}{(\code{data.frame} or \code{tibble})\cr alternative full dataset the rtables framework will use +\emph{only} when calculating column counts.} -\item{col_counts}{numeric (or \code{NULL}). Deprecated. If non-null, column counts -which override those calculated automatically during tabulation. Must -specify "counts" for \emph{all} resulting columns if non-NULL. \code{NA} -elements will be replaced with the automatically calculated counts.} +\item{col_counts}{(\code{numeric} or \code{NULL})\cr \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} if non-\code{NULL}, column counts +which override those calculated automatically during tabulation. Must specify "counts" for \emph{all} +resulting columns if non-\code{NULL}. \code{NA} elements will be replaced with the automatically calculated counts.} -\item{col_total}{integer(1). The total observations across all columns. -Defaults to \code{nrow(df)}.} +\item{col_total}{(\code{integer(1)})\cr the total observations across all columns. Defaults to \code{nrow(df)}.} -\item{topleft}{character. Override values for the "top left" material to be -displayed during printing.} +\item{topleft}{(\code{character})\cr override values for the "top left" material to be displayed during printing.} -\item{hsep}{character(1). Set of character(s) to be repeated as the separator -between the header and body of the table when rendered as text. Defaults to -a connected horizontal line (unicode 2014) in locals that use a UTF -charset, and to \code{-} elsewhere (with a once per session warning). See -\code{\link[formatters:default_horizontal_sep]{formatters::set_default_hsep()}} for further information.} +\item{hsep}{(\code{string})\cr set of characters to be repeated as the separator between the header and body of +the table when rendered as text. Defaults to a connected horizontal line (unicode 2014) in locals that use a UTF +charset, and to \code{-} elsewhere (with a once per session warning). See \code{\link[formatters:default_horizontal_sep]{formatters::set_default_hsep()}} for further +information.} -\item{\dots}{currently ignored.} +\item{...}{ignored.} } \value{ -A \code{TableTree} or \code{ElementaryTable} object representing the -table created by performing the tabulations declared in \code{lyt} to the -data \code{df}. +A \code{TableTree} or \code{ElementaryTable} object representing the table created by performing the tabulations +declared in \code{lyt} to the data \code{df}. } \description{ -Layouts are used to describe a table pre-data. \code{build_table} is used to -create a table using a layout and a dataset. +Layouts are used to describe a table pre-data. \code{build_table} is used to create a table +using a layout and a dataset. } \details{ -When \code{alt_counts_df} is specified, column counts are calculated by -applying the exact column subsetting expressions determined when applying -column splitting to the main data (\code{df}) to \code{alt_counts_df} and +When \code{alt_counts_df} is specified, column counts are calculated by applying the exact column subsetting +expressions determined when applying column splitting to the main data (\code{df}) to \code{alt_counts_df} and counting the observations in each resulting subset. -In particular, this means that in the case of splitting based on cuts of the -data, any dynamic cuts will have been calculated based on \code{df} and -simply re-used for the count calculation. +In particular, this means that in the case of splitting based on cuts of the data, any dynamic cuts will have +been calculated based on \code{df} and simply re-used for the count calculation. } \note{ -When overriding the column counts or totals care must be taken that, -e.g., \code{length()} or \code{nrow()} are not called within tabulation functions, -because those will NOT give the overridden counts. Writing/using tabulation -functions which accept \code{.N_col} and \code{.N_total} or do not rely on -column counts at all (even implicitly) is the only way to ensure overridden -counts are fully respected. +When overriding the column counts or totals care must be taken that, e.g., \code{length()} or \code{nrow()} are not called +within tabulation functions, because those will NOT give the overridden counts. Writing/using tabulation +functions which accept \code{.N_col} and \code{.N_total} or do not rely on column counts at all (even implicitly) is the +only way to ensure overridden counts are fully respected. } \examples{ lyt <- basic_table() \%>\% @@ -79,7 +69,6 @@ lyt <- basic_table() \%>\% "range" = diff(range(x)) ) }) - lyt tbl <- build_table(lyt, iris) diff --git a/man/cbind_rtables.Rd b/man/cbind_rtables.Rd index d7a1cddd4..4dbc7a6b0 100644 --- a/man/cbind_rtables.Rd +++ b/man/cbind_rtables.Rd @@ -2,26 +2,24 @@ % Please edit documentation in R/tt_compatibility.R \name{cbind_rtables} \alias{cbind_rtables} -\title{\code{cbind} two \code{rtables}} +\title{Column-bind two \code{TableTree} objects} \usage{ cbind_rtables(x, ...) } \arguments{ -\item{x}{A table or row object} +\item{x}{(\code{TableTree} or \code{TableRow})\cr a table or row object.} -\item{\dots}{1 or more further objects of the same class as \code{x}} +\item{...}{one or more further objects of the same class as \code{x}.} } \value{ A formal table object. } \description{ -\code{cbind} two \code{rtables} +Column-bind two \code{TableTree} objects } \examples{ x <- rtable(c("A", "B"), rrow("row 1", 1, 2), rrow("row 2", 3, 4)) - y <- rtable("C", rrow("row 1", 5), rrow("row 2", 6)) - z <- rtable("D", rrow("row 1", 9), rrow("row 2", 10)) t1 <- cbind_rtables(x, y) diff --git a/man/cell_values.Rd b/man/cell_values.Rd index 9e1a9680b..34ab79c07 100644 --- a/man/cell_values.Rd +++ b/man/cell_values.Rd @@ -13,36 +13,30 @@ value_at(tt, rowpath = NULL, colpath = NULL) \S4method{value_at}{VTableTree}(tt, rowpath = NULL, colpath = NULL) } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{rowpath}{character. Path in row-split space to the desired row(s). Can -include \code{"@content"}.} +\item{rowpath}{(\code{character})\cr path in row-split space to the desired row(s). Can include \code{"@content"}.} -\item{colpath}{character. Path in column-split space to the desired -column(s). Can include \code{"*"}.} +\item{colpath}{(\code{character})\cr path in column-split space to the desired column(s). Can include \code{"*"}.} -\item{omit_labrows}{logical(1). Should label rows underneath \code{rowpath} -be omitted (\code{TRUE}, the default), or return empty lists of cell -"values" (\code{FALSE}).} +\item{omit_labrows}{(\code{flag})\cr whether label rows underneath \code{rowpath} should be omitted (\code{TRUE}, the default), +or return empty lists of cell "values" (\code{FALSE}).} } \value{ -for \code{cell_values}, a \emph{list} (regardless of the type of -value the cells hold). if \code{rowpath} defines a path to a single row, -\code{cell_values} returns the list of cell values for that row, otherwise -a list of such lists, one for each row captured underneath \code{rowpath}. -This occurs after subsetting to \code{colpath} has occurred. - -For \code{value_at} the "unwrapped" value of a single cell, or an error, if -the combination of \code{rowpath} and \code{colpath} do not define the -location of a single cell in \code{tt}. +\itemize{ +\item \code{cell_values} returns a \code{list} (regardless of the type of value the cells hold). If \code{rowpath} defines a path to +a single row, \code{cell_values} returns the list of cell values for that row, otherwise a list of such lists, one for +each row captured underneath \code{rowpath}. This occurs after subsetting to \code{colpath} has occurred. +\item \code{value_at} returns the "unwrapped" value of a single cell, or an error, if the combination of \code{rowpath} and +\code{colpath} do not define the location of a single cell in \code{tt}. +} } \description{ Retrieve cell values by row and column path } \note{ -\code{cell_values} will return a single cell's value wrapped in a list. -Use \code{value_at} to receive the "bare" cell value. +\code{cell_values} will return a single cell's value wrapped in a list. Use \code{value_at} to receive the "bare" cell +value. } \examples{ lyt <- basic_table() \%>\% @@ -72,7 +66,6 @@ cell_values( ) cell_values(tbl, c("RACE", "ASIAN"), c("ARM", "A: Drug X", "SEX", "M")) - ## any arm, male columns from the ASIAN content (i.e. summary) row cell_values( tbl, c("RACE", "ASIAN", "@content"), @@ -101,4 +94,5 @@ cvnolist <- value_at( c("ARM", "B: Placebo", "SEX", "M") ) stopifnot(identical(cvlist[[1]], cvnolist)) + } diff --git a/man/cinfo.Rd b/man/cinfo.Rd index 4e2d65086..e7c93554b 100644 --- a/man/cinfo.Rd +++ b/man/cinfo.Rd @@ -4,7 +4,7 @@ \name{InstantiatedColumnInfo-class} \alias{InstantiatedColumnInfo-class} \alias{InstantiatedColumnInfo} -\title{\code{InstantiatedColumnInfo}} +\title{Instantiated column info} \usage{ InstantiatedColumnInfo( treelyt = LayoutColTree(), @@ -19,31 +19,29 @@ InstantiatedColumnInfo( ) } \arguments{ -\item{treelyt}{\code{LayoutColTree}.} +\item{treelyt}{(\code{LayoutColTree})\cr a \code{LayoutColTree} object.} -\item{csubs}{list. List of subsetting expressions} +\item{csubs}{(\code{list})\cr a list of subsetting expressions.} -\item{extras}{list. Extra arguments associated with the columns} +\item{extras}{(\code{list})\cr extra arguments associated with the columns.} -\item{cnts}{integer. Counts.} +\item{cnts}{(\code{integer})\cr counts.} -\item{total_cnt}{integer(1). Total observations represented across all -columns.} +\item{total_cnt}{(\code{integer(1)})\cr total observations represented across all columns.} -\item{dispcounts}{logical(1). Should the counts be displayed as header info when -the associated table is printed.} +\item{dispcounts}{(\code{flag})\cr whether the counts should be displayed as header info when the associated +table is printed.} -\item{countformat}{character(1). Format for the counts if they are displayed} +\item{countformat}{(\code{string})\cr format for the counts if they are displayed.} -\item{count_na_str}{character. NA string to be used when formatting counts. Defaults +\item{count_na_str}{(\code{character})\cr string to use in place of missing values when formatting counts. Defaults to \code{""}.} -\item{topleft}{character. Override values for the "top left" material to be -displayed during printing.} +\item{topleft}{(\code{character})\cr override values for the "top left" material to be displayed during printing.} } \value{ -an \code{InstantiateadColumnInfo} object. +An \code{InstantiateadColumnInfo} object. } \description{ -\code{InstantiatedColumnInfo} +Instantiated column info } diff --git a/man/clear_imods.Rd b/man/clear_imods.Rd index 5d9038b2a..cc80f8ca0 100644 --- a/man/clear_imods.Rd +++ b/man/clear_imods.Rd @@ -4,7 +4,7 @@ \alias{clear_indent_mods} \alias{clear_indent_mods,VTableTree-method} \alias{clear_indent_mods,TableRow-method} -\title{Clear All Indent Mods from a Table} +\title{Clear all indent modifiers from a table} \usage{ clear_indent_mods(tt) @@ -13,14 +13,13 @@ clear_indent_mods(tt) \S4method{clear_indent_mods}{TableRow}(tt) } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} } \value{ -The same class as \code{tt}, with all indent mods set to zero. +The same class as \code{tt}, with all indent modifiers set to zero. } \description{ -Clear All Indent Mods from a Table +Clear all indent modifiers from a table } \examples{ lyt1 <- basic_table() \%>\% @@ -32,4 +31,5 @@ lyt1 <- basic_table() \%>\% tbl1 <- build_table(lyt1, ex_adae) tbl1 clear_indent_mods(tbl1) + } diff --git a/man/col_accessors.Rd b/man/col_accessors.Rd index 9e50837d5..7ddebd48a 100644 --- a/man/col_accessors.Rd +++ b/man/col_accessors.Rd @@ -109,24 +109,24 @@ col_total(obj) <- value \S4method{col_total}{VTableNodeInfo}(obj) <- value } \arguments{ -\item{obj}{ANY. The object for the accessor to access or modify} +\item{obj}{(\code{ANY})\cr the object for the accessor to access or modify.} -\item{object}{The object to modify in-place} +\item{object}{(\code{ANY})\cr the object to modify in place.} -\item{value}{The new value} +\item{value}{(\code{ANY})\cr the new value.} -\item{df}{data.frame/NULL. Data to use if the column information is being -generated from a Pre-Data layout object} +\item{df}{(\code{data.frame} or \code{NULL})\cr data to use if the column information is being +generated from a pre-data layout object.} -\item{rtpos}{\code{TreePos}. Root position.} +\item{rtpos}{(\code{TreePos})\cr root position.} -\item{path}{character or NULL. \code{col_counts} getter and setter only. +\item{path}{(\code{character} or \code{NULL})\cr \code{col_counts} accessor and setter only. Path (in column structure).} } \value{ A \code{LayoutColTree} object. -Various column information, depending on the accessor used. +Returns various information about columns, depending on the accessor used. } \description{ Column information/structure accessors diff --git a/man/collect_leaves.Rd b/man/collect_leaves.Rd index e352fd9ed..bbf99eca2 100644 --- a/man/collect_leaves.Rd +++ b/man/collect_leaves.Rd @@ -2,21 +2,20 @@ % Please edit documentation in R/tree_accessors.R \name{collect_leaves} \alias{collect_leaves} -\title{Collect leaves of a table tree} +\title{Collect leaves of a \code{TableTree}} \usage{ collect_leaves(tt, incl.cont = TRUE, add.labrows = FALSE) } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{incl.cont}{logical. Include rows from content tables within the tree. Defaults to \code{TRUE}} +\item{incl.cont}{(\code{flag})\cr whether to include rows from content tables within the tree. Defaults to \code{TRUE}.} -\item{add.labrows}{logical. Include label rows. Defaults to \code{FALSE}} +\item{add.labrows}{(\code{flag})\cr whether to include label rows. Defaults to \code{FALSE}.} } \value{ -A list of \code{TableRow} objects for all rows in the table +A list of \code{TableRow} objects for all rows in the table. } \description{ -Collect leaves of a table tree +Collect leaves of a \code{TableTree} } diff --git a/man/compare_rtables.Rd b/man/compare_rtables.Rd index f7ac7d826..12e398f30 100644 --- a/man/compare_rtables.Rd +++ b/man/compare_rtables.Rd @@ -13,32 +13,32 @@ compare_rtables( ) } \arguments{ -\item{object}{\code{rtable} to test} +\item{object}{(\code{VTableTree})\cr \code{rtable} to test.} -\item{expected}{\code{rtable} expected} +\item{expected}{(\code{VTableTree})\cr expected \code{rtable}.} -\item{tol}{numerical tolerance} +\item{tol}{(\code{numeric(1)})\cr tolerance.} -\item{comp.attr}{boolean. Compare format of cells. Other attributes are +\item{comp.attr}{(\code{flag})\cr whether to compare cell formats. Other attributes are silently ignored.} -\item{structure}{boolean. Should structure (in the form of column and row -paths to cells) be compared. Currently defaults to \code{FALSE}, but this is +\item{structure}{(\code{flag})\cr whether structures (in the form of column and row +paths to cells) should be compared. Currently defaults to \code{FALSE}, but this is subject to change in future versions.} } \value{ -a matrix of class \code{"rtables_diff"} representing the differences +A matrix of class \code{rtables_diff} representing the differences between \code{object} and \code{expected} as described above. } \description{ Prints a matrix where \code{.} means cell matches, \code{X} means cell does -cells do not match, \code{+} cell (row) is missing, and \code{-} cell (row) +not match, \code{+} cell (row) is missing, and \code{-} cell (row) should not be there. If \code{structure} is set to \code{TRUE}, \code{C} indicates -columnar structure mismatch, \code{R} indicates row-structure mismatch, and +column-structure mismatch, \code{R} indicates row-structure mismatch, and \code{S} indicates mismatch in both row and column structure. } \note{ -In its current form \code{compare_rtables} does not take structure into +In its current form, \code{compare_rtables} does not take structure into account, only row and cell position. } \examples{ @@ -103,4 +103,5 @@ object <- rtable( ) compare_rtables(object, expected) + } diff --git a/man/compat_args.Rd b/man/compat_args.Rd index a4f035977..04b327562 100644 --- a/man/compat_args.Rd +++ b/man/compat_args.Rd @@ -2,36 +2,32 @@ % Please edit documentation in R/argument_conventions.R \name{compat_args} \alias{compat_args} -\title{Compatibility Arg Conventions} +\title{Compatibility argument conventions} \usage{ compat_args(.lst, row.name, format, indent, label, inset) } \arguments{ -\item{.lst}{list. An already-collected list of arguments to be used instead -of the elements of \code{\dots}. Arguments passed via \code{\dots} will be -ignored if this is specified.} +\item{.lst}{(\code{list})\cr an already-collected list of arguments to be used instead of the elements of \code{...}. +Arguments passed via \code{...} will be ignored if this is specified.} -\item{row.name}{if \code{NULL} then an empty string is used as -\code{row.name} of the \code{\link{rrow}}.} +\item{row.name}{(\code{string} or \code{NULL})\cr row name. If \code{NULL}, an empty string is used as \code{row.name} of the +\code{\link[=rrow]{rrow()}}.} -\item{format}{character(1) or function. The format label (string) or -formatter function to apply to the cell values passed via \code{...}. See -\code{\link[formatters]{list_valid_format_labels}} for currently supported -format labels.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr the format label (string) or formatter function to apply to the +cell values passed via \code{...}. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for currently supported format labels.} -\item{indent}{deprecated.} +\item{indent}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}} -\item{label}{character(1). A label (not to be confused with the name) for the -object/structure.} +\item{label}{(\code{string})\cr a label (not to be confused with the name) for the object/structure.} -\item{inset}{integer(1). The table inset for the row or table being -constructed. See \code{\link[formatters]{table_inset}}.} +\item{inset}{(\code{integer(1)})\cr the table inset for the row or table being constructed. See +\code{\link[formatters:table_inset]{formatters::table_inset()}} for details.} } \value{ -NULL (this is an argument template dummy function) +No return value. } \description{ -Compatibility Arg Conventions +Compatibility argument conventions } \seealso{ Other conventions: diff --git a/man/constr_args.Rd b/man/constr_args.Rd index fd307ed03..ab2eb7d40 100644 --- a/man/constr_args.Rd +++ b/man/constr_args.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/argument_conventions.R \name{constr_args} \alias{constr_args} -\title{Constructor Arg Conventions} +\title{Constructor argument conventions} \usage{ constr_args( kids, @@ -36,103 +36,87 @@ constr_args( ) } \arguments{ -\item{kids}{list. List of direct children.} +\item{kids}{(\code{list})\cr list of direct children.} -\item{cont}{\code{ElementaryTable}. Content table.} +\item{cont}{(\code{ElementaryTable})\cr content table.} -\item{lev}{integer. Nesting level (roughly, indentation level in practical -terms).} +\item{lev}{(\code{integer(1)})\cr nesting level (roughly, indentation level in practical terms).} -\item{iscontent}{logical. Is the \code{TableTree}/\code{ElementaryTable} being constructed -the content table for another \code{TableTree}.} +\item{iscontent}{(\code{flag})\cr whether the \code{TableTree}/\code{ElementaryTable} is being constructed as the content +table for another \code{TableTree}.} -\item{cinfo}{\code{InstantiatedColumnInfo} (or NULL). Column structure for the -object being created.} +\item{cinfo}{(\code{InstantiatedColumnInfo} or \code{NULL})\cr column structure for the object being created.} -\item{labelrow}{\code{LabelRow}. The \code{LabelRow} object to assign to this Table. -Constructed from \code{label} by default if not specified.} +\item{labelrow}{(\code{LabelRow})\cr the \code{LabelRow} object to assign to the table. Constructed from \code{label} by default +if not specified.} -\item{vals}{list. cell values for the row} +\item{vals}{(\code{list})\cr cell values for the row.} -\item{cspan}{integer. Column span. \code{1} indicates no spanning.} +\item{cspan}{(\code{integer})\cr column span. \code{1} indicates no spanning.} -\item{label_pos}{character(1). Location the variable label should be -displayed, Accepts \code{"hidden"} (default for non-analyze row splits), \code{"visible"}, -\code{"topleft"}, and - for analyze splits only - \code{"default"}. For analyze calls, -\code{"default"} indicates that the variable should be visible if and only if -multiple variables are analyzed at the same level of nesting.} +\item{label_pos}{(\code{string})\cr location where the variable label should be displayed. Accepts \code{"hidden"} +(default for non-analyze row splits), \code{"visible"}, \code{"topleft"}, and \code{"default"} (for analyze splits only). For +\code{analyze} calls, \code{"default"} indicates that the variable should be visible if and only if multiple variables are +analyzed at the same level of nesting.} -\item{cindent_mod}{numeric(1). The indent modifier for the content tables -generated by this split.} +\item{cindent_mod}{(\code{numeric(1)})\cr the indent modifier for the content tables generated by this split.} -\item{cvar}{character(1). The variable, if any, which the content function -should accept. Defaults to NA.} +\item{cvar}{(\code{string})\cr the variable, if any, that the content function should accept. Defaults to \code{NA}.} -\item{label}{character(1). A label (not to be confused with the name) for the -object/structure.} +\item{label}{(\code{string})\cr a label (not to be confused with the name) for the object/structure.} -\item{cextra_args}{list. Extra arguments to be passed to the content function -when tabulating row group summaries.} +\item{cextra_args}{(\code{list})\cr extra arguments to be passed to the content function when tabulating row group +summaries.} -\item{child_names}{character. Names to be given to the sub splits contained -by a compound split (typically a \code{AnalyzeMultiVars} split object).} +\item{child_names}{(\code{character})\cr names to be given to the subsplits contained by a compound split (typically +an \code{AnalyzeMultiVars} split object).} -\item{title}{character(1). Main title (\code{\link[=main_title]{main_title()}}) is a single string. -Ignored for subtables.} +\item{title}{(\code{string})\cr single string to use as main title (\code{\link[=main_title]{main_title()}}). Ignored for subtables.} -\item{subtitles}{character. Subtitles (\code{\link[=subtitles]{subtitles()}}) can be vector of strings, where -every element is printed in a separate line. Ignored for subtables.} +\item{subtitles}{(\code{character})\cr a vector of strings to use as subtitles (\code{\link[=subtitles]{subtitles()}}), where every element is +printed on a separate line. Ignored for subtables.} -\item{main_footer}{character. Main global (non-referential) footer materials -(\code{\link[=main_footer]{main_footer()}}). If it is a vector of strings, they will be printed on separate -lines.} +\item{main_footer}{(\code{character})\cr a vector of strings to use as main global (non-referential) footer materials +(\code{\link[=main_footer]{main_footer()}}), where every element is printed on a separate line.} -\item{prov_footer}{character. Provenance-related global footer materials -(\code{\link[=prov_footer]{prov_footer()}}). It can be also a vector of strings, printed on different lines. -Generally should not be modified by hand.} +\item{prov_footer}{(\code{character})\cr a vector of strings to use as provenance-related global footer materials +(\code{\link[=prov_footer]{prov_footer()}}), where every element is printed on a separate line.} -\item{footnotes}{list or NULL. Referential footnotes to be applied at current -level. In post-processing, this can be achieved with \code{\link{fnotes_at_path<-}}.} +\item{footnotes}{(\code{list} or \code{NULL})\cr referential footnotes to be applied at current level. In post-processing, +this can be achieved with \code{\link{fnotes_at_path<-}}.} -\item{page_title}{character. Page specific title(s).} +\item{page_title}{(\code{character})\cr page-specific title(s).} -\item{page_prefix}{character(1). Prefix, to be appended with the split value, -when forcing pagination between the children of this split/table} +\item{page_prefix}{(\code{string})\cr prefix to be appended with the split value when forcing pagination between +the children of a split/table.} -\item{section_div}{character(1). String which should be repeated as a section -divider after each group defined by this split instruction, or -\code{NA_character_} (the default) for no section divider.} +\item{section_div}{(\code{string})\cr string which should be repeated as a section divider after each group defined +by this split instruction, or \code{NA_character_} (the default) for no section divider.} -\item{trailing_section_div}{character(1). String which will be used as a section -divider after the printing of the last row contained in this (sub)-table, -unless that row is also the last table row to be printed overall, or -\code{NA_character_} for none (the default). When generated via layouting, this -would correspond to the \code{section_div} of the split under which this table -represents a single facet.} +\item{trailing_section_div}{(\code{string})\cr string which will be used as a section divider after the printing +of the last row contained in this (sub)table, unless that row is also the last table row to be printed overall, +or \code{NA_character_} for none (the default). When generated via layouting, this would correspond to the +\code{section_div} of the split under which this table represents a single facet.} -\item{split_na_str}{character. NA string vector for use with \code{split_format}.} +\item{split_na_str}{(\code{character})\cr NA string vector for use with \code{split_format}.} -\item{cna_str}{character. NA string for use with \code{cformat} for content -table.} +\item{cna_str}{(\code{character})\cr NA string for use with \code{cformat} for content table.} -\item{inset}{numeric(1). Number of spaces to inset the table header, table -body, referential footnotes, and main_footer, as compared to alignment -of title, subtitle, and provenance footer. Defaults to 0 (no inset).} +\item{inset}{(\code{numeric(1)})\cr number of spaces to inset the table header, table body, referential footnotes, and +main_footer, as compared to alignment of title, subtitle, and provenance footer. Defaults to 0 (no inset).} -\item{table_inset}{numeric(1). Number of spaces to inset the table header, table -body, referential footnotes, and main_footer, as compared to alignment -of title, subtitle, and provenance footer. Defaults to 0 (no inset).} +\item{table_inset}{(\code{numeric(1)})\cr number of spaces to inset the table header, table body, referential footnotes, +and main footer, as compared to alignment of title, subtitles, and provenance footer. Defaults to 0 (no inset).} -\item{header_section_div}{character(1). String which will be used to divide the header -from the table. See \code{\link[=header_section_div]{header_section_div()}} for getter and setter of these. -Please consider changing last element of \code{\link[=section_div]{section_div()}} when concatenating -tables that need a divider between them.} +\item{header_section_div}{(\code{string})\cr string which will be used to divide the header from the table. See +\code{\link[=header_section_div]{header_section_div()}} for the associated getter and setter. Please consider changing last element of +\code{\link[=section_div]{section_div()}} when concatenating tables that require a divider between them.} } \value{ -NULL (this is an argument template dummy function) +No return value. } \description{ -Constructor Arg Conventions +Constructor argument conventions } \seealso{ Other conventions: @@ -142,3 +126,4 @@ Other conventions: \code{\link{sf_args}()} } \concept{conventions} +\keyword{internal} diff --git a/man/content_table.Rd b/man/content_table.Rd index 737062e5f..f0c768059 100644 --- a/man/content_table.Rd +++ b/man/content_table.Rd @@ -3,21 +3,21 @@ \name{content_table} \alias{content_table} \alias{content_table<-} -\title{Retrieve or set Content Table from a \code{TableTree}} +\title{Retrieve or set content table from a \code{TableTree}} \usage{ content_table(obj) content_table(obj) <- value } \arguments{ -\item{obj}{\code{TableTree}. The \code{TableTree}} +\item{obj}{(\code{TableTree})\cr the table object.} -\item{value}{\code{ElementaryTable}. The new content table for \code{obj}.} +\item{value}{(\code{ElementaryTable})\cr the new content table for \code{obj}.} } \value{ -the \code{ElementaryTable} containing the (top level) \emph{content rows} of \code{obj} ( or \code{NULL} -if \code{obj} is not a formal table object). +the \code{ElementaryTable} containing the (top level) \emph{content rows} of \code{obj} (or \code{NULL} if \code{obj} is not +a formal table object). } \description{ -Returns the content table of \code{obj} if it is a \code{TableTree} object, or \code{NULL} otherwise +Returns the content table of \code{obj} if it is a \code{TableTree} object, or \code{NULL} otherwise. } diff --git a/man/counts_wpcts.Rd b/man/counts_wpcts.Rd index 8ace3a42f..417c06418 100644 --- a/man/counts_wpcts.Rd +++ b/man/counts_wpcts.Rd @@ -7,16 +7,17 @@ counts_wpcts(x, .N_col) } \arguments{ -\item{x}{factor. Vector of data, provided by rtables pagination machinery} +\item{x}{(\code{factor})\cr a vector of data, provided by rtables pagination machinery.} -\item{.N_col}{integer(1). Total count for the column, provided by rtables pagination machinery} +\item{.N_col}{(\code{integer(1)})\cr total count for the column, provided by rtables pagination machinery.} } \value{ -A \code{RowsVerticalSection} object with counts (and percents) for each level of the factor +A \code{RowsVerticalSection} object with counts (and percents) for each level of the factor. } \description{ Analysis function to count levels of a factor with percentage of the column total } \examples{ counts_wpcts(DM$SEX, 400) + } diff --git a/man/custom_split_funs.Rd b/man/custom_split_funs.Rd index ad7b296d7..37081c939 100644 --- a/man/custom_split_funs.Rd +++ b/man/custom_split_funs.Rd @@ -2,55 +2,43 @@ % Please edit documentation in R/split_funs.R \name{custom_split_funs} \alias{custom_split_funs} -\title{Custom Split Functions} +\title{Custom split functions} \description{ -Split functions provide the work-horse for \code{rtables}'s -generalized partitioning. These functions accept a (sub)set of incoming -data, a split object, and return 'splits' of that data. +Split functions provide the work-horse for \code{rtables}'s generalized partitioning. These functions accept a (sub)set +of incoming data and a split object, and return "splits" of that data. } \section{Custom Splitting Function Details}{ -User-defined custom split functions can perform any type of computation on -the incoming data provided that they meet the contract for generating -'splits' of the incoming data 'based on' the split object. +User-defined custom split functions can perform any type of computation on the incoming data provided that they +meet the requirements for generating "splits" of the incoming data based on the split object. Split functions are functions that accept: \describe{ -\item{df}{data.frame of incoming data to be split} -\item{spl}{a Split object. this is largely an internal detail custom -functions will not need to worry about, but \code{obj_name(spl)}, for -example, will give the name of the split as it will appear in paths in the -resulting table} -\item{vals}{Any pre-calculated values. If given non-null values, the values -returned should match these. Should be NULL in most cases and can likely be -ignored} -\item{labels}{Any pre-calculated value labels. Same as above for -\code{values}} -\item{trim}{If \code{TRUE}, resulting splits that are empty should be -removed} -\item{(Optional) .spl_context}{a data.frame describing previously performed -splits which collectively arrived at \code{df}} +\item{df}{a \code{data.frame} of incoming data to be split.} +\item{spl}{a Split object. This is largely an internal detail custom functions will not need to worry about, +but \code{obj_name(spl)}, for example, will give the name of the split as it will appear in paths in the resulting +table.} +\item{vals}{any pre-calculated values. If given non-\code{NULL} values, the values returned should match these. +Should be \code{NULL} in most cases and can usually be ignored.} +\item{labels}{any pre-calculated value labels. Same as above for \code{values}.} +\item{trim}{if \code{TRUE}, resulting splits that are empty are removed.} +\item{(optional) .spl_context}{a \code{data.frame} describing previously performed splits which collectively +arrived at \code{df}.} } -The function must then output a \code{named list} with the following -elements: +The function must then output a named \code{list} with the following elements: \describe{ -\item{values}{The vector of all values corresponding to the splits of -\code{df}} -\item{datasplit}{a list of data.frames representing the groupings of the -actual observations from \code{df}.} -\item{labels}{a character vector giving a string label for each value listed -in the \code{values} element above} -\item{(Optional) extras}{If present, extra arguments are to be passed to summary -and analysis functions whenever they are executed on the corresponding -element of \code{datasplit} or a subset thereof} +\item{values}{the vector of all values corresponding to the splits of \code{df}.} +\item{datasplit}{a list of \code{data.frame}s representing the groupings of the actual observations from \code{df}.} +\item{labels}{a character vector giving a string label for each value listed in the \code{values} element above.} +\item{(optional) extras}{if present, extra arguments are to be passed to summary and analysis functions +whenever they are executed on the corresponding element of \code{datasplit} or a subset thereof.} } -One way to generate custom splitting functions is to wrap existing split -functions and modify either the incoming data before they are called or -their outputs. +One way to generate custom splitting functions is to wrap existing split functions and modify either the incoming +data before they are called or their outputs. } \examples{ @@ -94,6 +82,6 @@ tbl } \seealso{ -\code{\link[=make_split_fun]{make_split_fun()}} for the API for creating custom split functions, -and \link{split_funcs} for a variety of pre-defined split functions. +\code{\link[=make_split_fun]{make_split_fun()}} for the API for creating custom split functions, and \link{split_funcs} for a variety of +pre-defined split functions. } diff --git a/man/cutsplits.Rd b/man/cutsplits.Rd index b7542f412..edf7de855 100644 --- a/man/cutsplits.Rd +++ b/man/cutsplits.Rd @@ -56,84 +56,70 @@ VarDynCutSplit( ) } \arguments{ -\item{var}{string, variable name} +\item{var}{(\code{string})\cr variable name.} -\item{split_label}{string. Label string to be associated with the table -generated by the split. Not to be confused with labels assigned to each -child (which are based on the data and type of split during tabulation).} +\item{split_label}{(\code{string})\cr label to be associated with the table generated by the split. Not to be confused +with labels assigned to each child (which are based on the data and type of split during tabulation).} -\item{cuts}{numeric. Cuts to use} +\item{cuts}{(\code{numeric})\cr cuts to use.} -\item{cutlabels}{character (or NULL). Labels for the cuts} +\item{cutlabels}{(\code{character} or \code{NULL})\cr labels for the cuts.} -\item{cfun}{list/function/NULL. tabulation function(s) for creating content -rows. Must accept \code{x} or \code{df} as first parameter. Must accept -\code{labelstr} as the second argument. Can optionally accept all optional -arguments accepted by analysis functions. See \code{\link{analyze}}.} +\item{cfun}{(\code{list}, \code{function}, or \code{NULL})\cr tabulation function(s) for creating content rows. Must accept \code{x} +or \code{df} as first parameter. Must accept \code{labelstr} as the second argument. Can optionally accept all optional +arguments accepted by analysis functions. See \code{\link[=analyze]{analyze()}}.} -\item{cformat}{format spec. Format for content rows} +\item{cformat}{(\code{string}, \code{function}, or \code{list})\cr format for content rows.} -\item{cna_str}{character. NA string for use with \code{cformat} for content -table.} +\item{cna_str}{(\code{character})\cr NA string for use with \code{cformat} for content table.} -\item{split_format}{\code{FormatSpec}. Default format associated with the split -being created.} +\item{split_format}{(\code{string}, \code{function}, or \code{list})\cr default format associated with the split being created.} -\item{split_na_str}{character. NA string vector for use with \code{split_format}.} +\item{split_na_str}{(\code{character})\cr NA string vector for use with \code{split_format}.} -\item{split_name}{string. Name associated with this split (for pathing, etc)} +\item{split_name}{(\code{string})\cr name associated with the split (for pathing, etc.).} -\item{child_labels}{string. One of \code{"default"}, \code{"visible"}, -\code{"hidden"}. What should the display behavior be for the labels (i.e. -label rows) of the children of this split. Defaults to \code{"default"} -which flags the label row as visible only if the child has 0 content rows.} +\item{child_labels}{(\code{string})\cr the display behavior for the labels (i.e. label rows) of the children of this +split. Accepts \code{"default"}, \code{"visible"}, and \code{"hidden"}. Defaults to \code{"default"} which flags the label row as +visible only if the child has 0 content rows.} -\item{extra_args}{list. Extra arguments to be passed to the tabulation -function. Element position in the list corresponds to the children of this -split. Named elements in the child-specific lists are ignored if they do +\item{extra_args}{(\code{list})\cr extra arguments to be passed to the tabulation function. Element position in the list +corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do not match a formal argument of the tabulation function.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} -\item{cindent_mod}{numeric(1). The indent modifier for the content tables -generated by this split.} +\item{cindent_mod}{(\code{numeric(1)})\cr the indent modifier for the content tables generated by this split.} -\item{cvar}{character(1). The variable, if any, which the content function -should accept. Defaults to NA.} +\item{cvar}{(\code{string})\cr the variable, if any, that the content function should accept. Defaults to \code{NA}.} -\item{cextra_args}{list. Extra arguments to be passed to the content function -when tabulating row group summaries.} +\item{cextra_args}{(\code{list})\cr extra arguments to be passed to the content function when tabulating row group +summaries.} -\item{label_pos}{character(1). Location the variable label should be -displayed, Accepts \code{"hidden"} (default for non-analyze row splits), \code{"visible"}, -\code{"topleft"}, and - for analyze splits only - \code{"default"}. For analyze calls, -\code{"default"} indicates that the variable should be visible if and only if -multiple variables are analyzed at the same level of nesting.} +\item{label_pos}{(\code{string})\cr location where the variable label should be displayed. Accepts \code{"hidden"} +(default for non-analyze row splits), \code{"visible"}, \code{"topleft"}, and \code{"default"} (for analyze splits only). For +\code{analyze} calls, \code{"default"} indicates that the variable should be visible if and only if multiple variables are +analyzed at the same level of nesting.} -\item{cumulative}{logical. Should the cuts be treated as cumulative. Defaults -to \code{FALSE}} +\item{cumulative}{(\code{flag})\cr whether the cuts should be treated as cumulative. Defaults to \code{FALSE}.} -\item{page_prefix}{character(1). Prefix, to be appended with the split value, -when forcing pagination between the children of this split/table} +\item{page_prefix}{(\code{string})\cr prefix to be appended with the split value when forcing pagination between +the children of a split/table.} -\item{section_div}{character(1). String which should be repeated as a section -divider after each group defined by this split instruction, or -\code{NA_character_} (the default) for no section divider.} +\item{section_div}{(\code{string})\cr string which should be repeated as a section divider after each group defined +by this split instruction, or \code{NA_character_} (the default) for no section divider.} -\item{cutfun}{function. Function which accepts the \emph{full vector} of -\code{var} values and returns cut points to be used (via \code{cut}) when -splitting data during tabulation} +\item{cutfun}{(\code{function})\cr function which accepts the \emph{full vector} of \code{var} values and returns cut points to be +used (via \code{cut}) when splitting data during tabulation.} -\item{cutlabelfun}{function. Function which returns either labels for the -cuts or NULL when passed the return value of \code{cutfun}} +\item{cutlabelfun}{(\code{function})\cr function which returns either labels for the cuts or \code{NULL} when passed the +return value of \code{cutfun}.} } \value{ -a \code{VarStaticCutSplit}, \code{CumulativeCutSplit} object for -\code{make_static_cut_split}, or a \code{VarDynCutSplit} object for -\code{VarDynCutSplit()} +A \code{VarStaticCutSplit}, \code{CumulativeCutSplit} object for \code{make_static_cut_split}, or a \code{VarDynCutSplit} +object for \code{\link[=VarDynCutSplit]{VarDynCutSplit()}}. } \description{ Splits for cutting by values of a numeric variable diff --git a/man/data.frame_export.Rd b/man/data.frame_export.Rd index 3584cd8a4..6800fda86 100644 --- a/man/data.frame_export.Rd +++ b/man/data.frame_export.Rd @@ -5,7 +5,7 @@ \alias{as_result_df} \alias{result_df_specs} \alias{path_enriched_df} -\title{Generate a Result Data Frame} +\title{Generate a result data frame} \usage{ as_result_df(tt, spec = "v0_experimental", simplify = FALSE, ...) @@ -14,17 +14,14 @@ result_df_specs() path_enriched_df(tt, path_fun = collapse_path, value_fun = collapse_values) } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{spec}{character(1). The specification to use to -extract the result data frame. See details} +\item{spec}{(\code{string})\cr the specification to use to extract the result data frame. See Details below.} -\item{simplify}{logical(1). If \code{TRUE}, the result data frame will have only visible -labels and result columns.} +\item{simplify}{(\code{flag})\cr whether the result data frame should only have labels and result columns visible.} -\item{...}{Passed to spec-specific result data frame conversion function. Currently it can be -one or more of the following parameters (valid only for \code{v0_experimental} spec for now): +\item{...}{additional arguments passed to spec-specific result data frame conversion function. Currently it can be +one or more of the following parameters (valid only for \code{v0_experimental} spec. for now): \itemize{ \item \code{expand_colnames}: when \code{TRUE}, the result data frame will have expanded column names above the usual output. This is useful when the result data frame is used for further processing. @@ -41,23 +38,28 @@ but without information about the row structure. Row labels will be assigned to with \code{\link[=df_to_tt]{df_to_tt()}}. }} -\item{path_fun}{function. Function to transform paths into single-string -row/column names.} +\item{path_fun}{(\code{function})\cr function to transform paths into single-string row/column names.} -\item{value_fun}{function. Function to transform cell values into cells of -the data.frame. Defaults to \code{collapse_values} which creates strings -where multi-valued cells are collapsed together, separated by \code{|}.} +\item{value_fun}{(\code{function})\cr function to transform cell values into cells of a \code{data.frame}. Defaults to +\code{collapse_values}, which creates strings where multi-valued cells are collapsed together, separated by \code{|}.} } \value{ -\code{result_df_specs()}: returns a named list of result data frame extraction functions by "specification". +\itemize{ +\item \code{as_result_df} returns a result \code{data.frame}. +} -\code{path_enriched_df()}: returns a data frame of \code{tt}'s cell values (processed by -\code{value_fun}, with columns named by the full column paths (processed by -\code{path_fun} and an additional \code{row_path} column with the row paths -(processed by by \code{path_fun}). +\itemize{ +\item \code{result_df_specs()} returns a named list of result data frame extraction functions by "specification". +} + +\itemize{ +\item \code{path_enriched_df()} returns a \code{data.frame} of \code{tt}'s cell values (processed by \code{value_fun}, with columns named by +the full column paths (processed by \code{path_fun} and an additional \code{row_path} column with the row paths (processed +by \code{path_fun}). +} } \description{ -Collection of utilities to extract \code{data.frame} from \code{TableTree} objects. +Collection of utilities to extract \code{data.frame} objects from \code{TableTree} objects. } \details{ \code{as_result_df()}: Result data frame specifications may differ in the exact information @@ -67,9 +69,9 @@ suffix will remain available \emph{including any bugs in their construction} ind } \section{Functions}{ \itemize{ -\item \code{result_df_specs()}: list of functions that extract result data frames from \code{TableTree}s. +\item \code{result_df_specs()}: A list of functions that extract result data frames from \code{TableTree}s. -\item \code{path_enriched_df()}: transform \code{TableTree} object to Path-Enriched \code{data.frame}. +\item \code{path_enriched_df()}: Transform a \code{TableTree} object to a path-enriched \code{data.frame}. }} \examples{ diff --git a/man/df_to_tt.Rd b/man/df_to_tt.Rd index a2f7518c7..87209bfd4 100644 --- a/man/df_to_tt.Rd +++ b/man/df_to_tt.Rd @@ -2,25 +2,20 @@ % Please edit documentation in R/tt_from_df.R \name{df_to_tt} \alias{df_to_tt} -\title{Create \code{ElementaryTable} from data.frame} +\title{Create an \code{ElementaryTable} from a \code{data.frame}} \usage{ df_to_tt(df) } \arguments{ -\item{df}{data.frame.} -} -\value{ -an \code{ElementaryTable} object with unnested columns corresponding to -\code{names(df)} and row labels corresponding to \code{row.names(df)}. +\item{df}{(\code{data.frame})\cr a data frame.} } \description{ -Create \code{ElementaryTable} from data.frame +Create an \code{ElementaryTable} from a \code{data.frame} } \details{ -If row names are not defined in \code{df} (or they are simple numbers), then the -row names are taken from the column \code{label_name}, if exists. If \code{label_name} exists, -then it is also removed from the original data. Remember that this behavior is -compatible with \code{\link[=as_result_df]{as_result_df()}}, when \code{as_is = TRUE} and the row names are not unique. +If row names are not defined in \code{df} (or they are simple numbers), then the row names are taken from the column +\code{label_name}, if it exists. If \code{label_name} exists, then it is also removed from the original data. This behavior +is compatible with \code{\link[=as_result_df]{as_result_df()}}, when \code{as_is = TRUE} and the row names are not unique. } \examples{ df_to_tt(mtcars) diff --git a/man/dimensions.Rd b/man/dimensions.Rd index f885768a3..49a92c432 100644 --- a/man/dimensions.Rd +++ b/man/dimensions.Rd @@ -4,7 +4,7 @@ \alias{nrow,VTableTree-method} \alias{ncol,VTableNodeInfo-method} \alias{dim,VTableNodeInfo-method} -\title{Table Dimensions} +\title{Table dimensions} \usage{ \S4method{nrow}{VTableTree}(x) @@ -13,13 +13,13 @@ \S4method{dim}{VTableNodeInfo}(x) } \arguments{ -\item{x}{\code{TableTree} or \code{ElementaryTable} object} +\item{x}{(\code{TableTree} or \code{ElementaryTable})\cr a table object.} } \value{ -the number of rows (\code{nrow}), columns (\code{ncol}) or both (\code{dim}) of the object. +The number of rows (\code{nrow}), columns (\code{ncol}), or both (\code{dim}) of the object. } \description{ -Table Dimensions +Table dimensions } \examples{ lyt <- basic_table() \%>\% diff --git a/man/do_base_split.Rd b/man/do_base_split.Rd index 1cf0c4ab6..99997f8c5 100644 --- a/man/do_base_split.Rd +++ b/man/do_base_split.Rd @@ -2,33 +2,29 @@ % Please edit documentation in R/split_funs.R \name{do_base_split} \alias{do_base_split} -\title{Apply Basic Split (For Use In Custom Split Functions)} +\title{Apply basic split (for use in custom split functions)} \usage{ do_base_split(spl, df, vals = NULL, labels = NULL, trim = FALSE) } \arguments{ -\item{spl}{A Split object defining a partitioning or analysis/tabulation of -the data.} +\item{spl}{(\code{Split})\cr a \code{Split} object defining a partitioning or analysis/tabulation of the data.} -\item{df}{dataset (\code{data.frame} or \code{tibble})} +\item{df}{(\code{data.frame} or \code{tibble})\cr dataset.} -\item{vals}{ANY. Already calculated/known values of the split. Generally -should be left as \code{NULL}.} +\item{vals}{(\code{ANY})\cr already calculated/known values of the split. Generally should be left as \code{NULL}.} -\item{labels}{character. Labels associated with \code{vals}. Should be -\code{NULL} when \code{vals} is, which should almost always be the case.} +\item{labels}{(\code{character})\cr labels associated with \code{vals}. Should be \code{NULL} whenever \code{vals} is, which should +almost always be the case.} -\item{trim}{logical(1). Should groups corresponding to empty data subsets be -removed. Defaults to \code{FALSE}.} +\item{trim}{(\code{flag})\cr whether groups corresponding to empty data subsets should be removed. Defaults to +\code{FALSE}.} } \value{ -the result of the split being applied as if it had no custom split -function, see \code{\link{custom_split_funs}} +The result of the split being applied as if it had no custom split function. See \link{custom_split_funs}. } \description{ -This function is intended for use inside custom split functions. It applies -the current split \emph{as if it had no custom splitting function} so that -those default splits can be further manipulated. +This function is intended for use inside custom split functions. It applies the current split \emph{as if it had no +custom splitting function} so that those default splits can be further manipulated. } \examples{ uneven_splfun <- function(df, spl, vals = NULL, labels = NULL, trim = FALSE) { @@ -53,4 +49,5 @@ lyt <- basic_table() \%>\% tbl <- build_table(lyt, subset(ex_adae, as.numeric(ARM) <= 2)) tbl + } diff --git a/man/drop_facet_levels.Rd b/man/drop_facet_levels.Rd index b8a5399dc..77dbb4af8 100644 --- a/man/drop_facet_levels.Rd +++ b/man/drop_facet_levels.Rd @@ -2,24 +2,23 @@ % Please edit documentation in R/make_split_fun.R \name{drop_facet_levels} \alias{drop_facet_levels} -\title{Preprocessing Functions for use in make_split_fun} +\title{Pre-processing function for use in \code{make_split_fun}} \usage{ drop_facet_levels(df, spl, ...) } \arguments{ -\item{df}{data.frame. The incoming data corresponding with the parent facet} +\item{df}{(\code{data.frame})\cr the incoming data corresponding with the parent facet.} -\item{spl}{Split.} +\item{spl}{(\code{VarLevelSplit})\cr the split.} -\item{...}{dots. This is used internally to pass parameters.} +\item{...}{additional parameters passed internally.} } \description{ -This function is intended for use as a preprocessing -component in \code{make_split_fun}, and should not be called +This function is intended for use as a pre-processing component in \code{make_split_fun}, and should not be called directly by end users. } \seealso{ -make_split_fun +\code{\link[=make_split_fun]{make_split_fun()}} Other make_custom_split: \code{\link{add_combo_facet}()}, diff --git a/man/export_as_docx.Rd b/man/export_as_docx.Rd index faaa94124..b58b95853 100644 --- a/man/export_as_docx.Rd +++ b/man/export_as_docx.Rd @@ -27,55 +27,49 @@ margins_potrait() margins_landscape() } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{file}{character(1). String that indicates the final file output. It needs to have \code{.docx} -extension.} +\item{file}{(\code{string})\cr string that indicates the final file output. Must have \code{.docx} extension.} -\item{doc_metadata}{list of character(1)s. Any value that can be used as metadata by -\code{?officer::set_doc_properties}. Important text values are \verb{title, subject, creator, description} +\item{doc_metadata}{(\code{list} of \code{string}s)\cr any value that can be used as metadata by +\code{?officer::set_doc_properties}. Important text values are \code{title}, \code{subject}, \code{creator}, and \code{description}, while \code{created} is a date object.} -\item{titles_as_header}{logical(1). Defaults to \code{TRUE} for \code{\link[=tt_to_flextable]{tt_to_flextable()}}, so the -table is self-contained as it makes additional header rows for \code{\link[=main_title]{main_title()}} -string and \code{\link[=subtitles]{subtitles()}} character vector (one per element). \code{FALSE} is suggested -for \code{\link[=export_as_docx]{export_as_docx()}}. This adds titles and subtitles as a text paragraph above -the table. Same style is applied.} +\item{titles_as_header}{(\code{flag})\cr defaults to \code{TRUE} for \code{\link[=tt_to_flextable]{tt_to_flextable()}}, so the table is self-contained +as it makes additional header rows for \code{\link[=main_title]{main_title()}} string and \code{\link[=subtitles]{subtitles()}} character vector (one per element). +\code{FALSE} is suggested for \code{\link[=export_as_docx]{export_as_docx()}}. This adds titles and subtitles as a text paragraph above the table. +The same style is applied.} -\item{footers_as_text}{logical(1). Defaults to \code{FALSE} for \code{\link[=tt_to_flextable]{tt_to_flextable()}}, so -the table is self-contained with the \code{flextable} definition of footnotes. \code{TRUE} is -used for \code{\link[=export_as_docx]{export_as_docx()}} to add the footers as a new paragraph after the table. -Same style is applied, but with a smaller font.} +\item{footers_as_text}{(\code{flag})\cr defaults to \code{FALSE} for \code{\link[=tt_to_flextable]{tt_to_flextable()}}, so the table is self-contained with +the \code{flextable} definition of footnotes. \code{TRUE} is used for \code{\link[=export_as_docx]{export_as_docx()}} to add the footers as a new +paragraph after the table. The same style is applied, but with a smaller font.} -\item{template_file}{character(1). Template file that \code{officer} will use as a starting -point for the final document. It will attach the table and use the defaults defined in -the template file. Output will be doc \code{file} nonetheless.} +\item{template_file}{(\code{string})\cr template file that \code{officer} will use as a starting point for the final +document. Document attaches the table and uses the defaults defined in the template file.} -\item{section_properties}{\code{officer::prop_section} object. Here you can set margins and page -size.} +\item{section_properties}{(\code{officer::prop_section})\cr an \code{\link[officer:prop_section]{officer::prop_section()}} object which sets margins and +page size.} } \description{ From a table, produce a self-contained word document or attach it to a template word -file (\code{template_file}). This function is based on \code{\link[=tt_to_flextable]{tt_to_flextable()}} transformer and -\code{officer} package. +file (\code{template_file}). This function is based on the \code{\link[=tt_to_flextable]{tt_to_flextable()}} transformer and +the \code{officer} package. } \section{Functions}{ \itemize{ -\item \code{section_properties_portrait()}: helper function that defines standard portrait properties for tables. +\item \code{section_properties_portrait()}: Helper function that defines standard portrait properties for tables. -\item \code{section_properties_landscape()}: helper function that defines standard landscape properties for tables. +\item \code{section_properties_landscape()}: Helper function that defines standard landscape properties for tables. -\item \code{margins_potrait()}: helper function that defines standard portrait margins for tables. +\item \code{margins_potrait()}: Helper function that defines standard portrait margins for tables. -\item \code{margins_landscape()}: helper function that defines standard landscape margins for tables. +\item \code{margins_landscape()}: Helper function that defines standard landscape margins for tables. }} \note{ -\code{export_as_docx()} does not have many options available. We suggest, if you need -specific formats and details to use \code{\link[=tt_to_flextable]{tt_to_flextable()}} first and then \code{export_as_docx}. -Only \code{title_as_header} and \code{footer_as_text} need to be specified again if changed in -\code{tt_to_flextable()}. +\code{export_as_docx()} has few customization options available. If you require specific formats and details, +we suggest that you use \code{\link[=tt_to_flextable]{tt_to_flextable()}} prior to \code{export_as_docx}. Only the \code{title_as_header} and +\code{footer_as_text} parameters must be re-specified if the table is changed first using \code{\link[=tt_to_flextable]{tt_to_flextable()}}. } \examples{ lyt <- basic_table() \%>\% @@ -89,6 +83,7 @@ tbl <- build_table(lyt, ex_adsl) tf <- tempfile(fileext = ".docx") export_as_docx(tbl, file = tf, section_properties = section_properties_portrait()) } + } \seealso{ \code{\link[=tt_to_flextable]{tt_to_flextable()}} diff --git a/man/find_degen_struct.Rd b/man/find_degen_struct.Rd index f43c6cf25..bc10e0348 100644 --- a/man/find_degen_struct.Rd +++ b/man/find_degen_struct.Rd @@ -2,26 +2,29 @@ % Please edit documentation in R/validate_table_struct.R \name{find_degen_struct} \alias{find_degen_struct} -\title{Find degenerate (sub)structures within a table (Experimental)} +\title{Find degenerate (sub)structures within a table} \usage{ find_degen_struct(tt) } \arguments{ -\item{tt}{\code{TableTree} - -This function returns a list with the row-paths to all -structural subtables which contain no data rows ( -even if they have associated content rows).} +\item{tt}{(\code{TableTree})\cr a \code{TableTree} object.} } \value{ -a list of character vectors representing the -row paths, if any, to degenerate substructures within -the table. +A list of character vectors representing the row paths, if any, to degenerate substructures within the table. } \description{ -Find degenerate (sub)structures within a table (Experimental) +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} + +This function returns a list with the row-paths to all structural subtables which contain no data rows (even if +they have associated content rows). } \examples{ find_degen_struct(rtable("hi")) } +\seealso{ +Other table structure validation functions: +\code{\link{sanitize_table_struct}()}, +\code{\link{validate_table_struct}()} +} +\concept{table structure validation functions} diff --git a/man/format_rcell.Rd b/man/format_rcell.Rd index 6269181f9..fa2fb10fe 100644 --- a/man/format_rcell.Rd +++ b/man/format_rcell.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/format_rcell.R \name{format_rcell} \alias{format_rcell} -\title{Format \code{rcell}} +\title{Format \code{rcell} objects} \usage{ format_rcell( x, @@ -15,30 +15,27 @@ format_rcell( ) } \arguments{ -\item{x}{an object of class \code{\link{CellValue}}, or a raw value.} +\item{x}{(\code{CellValue} or \code{ANY})\cr an object of class \code{CellValue}, or a raw value.} -\item{format}{character(1) or function. The format label (string) or -formatter function to apply to \code{x}.} +\item{format}{(\code{string} or \code{function})\cr the format label or formatter function to +apply to \code{x}.} -\item{output}{character(1). Output type.} +\item{output}{(\code{string})\cr output type.} -\item{na_str}{character(1). String that should be displayed when the value of -\code{x} is missing. Defaults to \code{"NA"}.} +\item{na_str}{(\code{string})\cr string that should be displayed when the value of \code{x} is missing. Defaults to \code{"NA"}.} -\item{pr_row_format}{list of default format coming from the general row.} +\item{pr_row_format}{(\code{list})\cr list of default formats coming from the general row.} -\item{pr_row_na_str}{list of default \code{"NA"} string coming from the general row.} +\item{pr_row_na_str}{(\code{list})\cr list of default \code{"NA"} strings coming from the general row.} -\item{shell}{logical(1). Should the formats themselves be returned instead of the +\item{shell}{(\code{flag})\cr whether the formats themselves should be returned instead of the values with formats applied. Defaults to \code{FALSE}.} } \value{ -formatted text representing the cell +Formatted text. } \description{ -This is a wrapper around -\code{\link[formatters:format_value]{formatters::format_value}} for use with -\code{CellValue} objects +This is a wrapper for \code{\link[formatters:format_value]{formatters::format_value()}} for use with \code{CellValue} objects } \examples{ cll <- CellValue(pi, format = "xx.xxx") diff --git a/man/formatters_methods.Rd b/man/formatters_methods.Rd index 41e60e1cc..d2ffe1ef9 100644 --- a/man/formatters_methods.Rd +++ b/man/formatters_methods.Rd @@ -2,6 +2,7 @@ % Please edit documentation in R/tree_accessors.R, R/tt_paginate.R \name{obj_name,VNodeInfo-method} \alias{obj_name,VNodeInfo-method} +\alias{formatters_methods} \alias{obj_name,Split-method} \alias{obj_name<-,VNodeInfo-method} \alias{obj_name<-,Split-method} @@ -37,7 +38,6 @@ \alias{table_inset<-,VTableNodeInfo-method} \alias{table_inset<-,PreDataTableLayouts-method} \alias{table_inset<-,InstantiatedColumnInfo-method} -\alias{formatters_methods} \alias{nlines,TableRow-method} \alias{nlines,LabelRow-method} \alias{nlines,RefFootnote-method} @@ -173,68 +173,63 @@ ) } \arguments{ -\item{obj}{ANY. The object for the accessor to access or modify} +\item{obj}{(\code{ANY})\cr the object for the accessor to access or modify.} -\item{value}{The new value} +\item{value}{(\code{ANY})\cr the new value.} -\item{x}{An object} +\item{x}{(\code{ANY})\cr an object.} -\item{colwidths}{numeric vector. Column widths for use with vertical pagination.} +\item{colwidths}{(\code{numeric})\cr a vector of column widths for use in vertical pagination.} -\item{max_width}{numeric(1). Width strings should be wrapped to -when determining how many lines they require.} +\item{max_width}{(\code{numeric(1)})\cr width that strings should be wrapped to when +determining how many lines they require.} -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{visible_only}{logical(1). Should only visible aspects of the table structure be reflected in this summary. -Defaults to \code{TRUE}. May not be supported by all methods.} +\item{visible_only}{(\code{flag})\cr should only visible aspects of the table structure be reflected +in this summary. Defaults to \code{TRUE}. May not be supported by all methods.} -\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. A vector path for a position within the structure of a -\code{tabletree}. Each element represents a subsequent choice amongst the children -of the previous choice.} +\item{path}{(\code{character})\cr a vector path for a position within the structure of a \code{TableTree}. Each element +represents a subsequent choice amongst the children of the previous choice.} -\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{ -for getters, the current value of the component being accessed -on \code{obj}, for setters, a modified copy of \code{obj} with the new value. +\itemize{ +\item Accessor functions return the current value of the component being accessed of \code{obj} +\item Setter functions return a modified copy of \code{obj} with the new value. +} } \description{ See the \code{formatters} documentation for descriptions of these generics. } \details{ -When \code{visible_only} is \code{TRUE} (the default), -methods should return a data.frame with exactly one row per -visible row in the table-like object. This is useful when -reasoning about how a table will print, but does not reflect -the full pathing space of the structure (though the paths which -are given will all work as is). - -If supported, when \code{visible_only} is \code{FALSE}, every -structural element of the table (in row-space) will be reflected in -the returned data.frame, meaning the full pathing-space will be -represented but some rows in the layout summary will not represent -printed rows in the table as it is displayed. - -Most arguments beyond \code{tt} and \code{visible_only} are present so that -\code{make_row_df} methods can call \code{make_row_df} recursively and retain information, -and should not be set during a top-level call +When \code{visible_only} is \code{TRUE} (the default), methods should return a \code{data.frame} with exactly one +row per visible row in the table-like object. This is useful when reasoning about how a table will +print, but does not reflect the full pathing space of the structure (though the paths which are given +will all work as is). + +If supported, when \code{visible_only} is \code{FALSE}, every structural element of the table (in row-space) +will be reflected in the returned \code{data.frame}, meaning the full pathing-space will be represented +but some rows in the layout summary will not represent printed rows in the table as it is displayed. + +Most arguments beyond \code{tt} and \code{visible_only} are present so that \code{make_row_df} methods can call +\code{make_row_df} recursively and retain information, and should not be set during a top-level call. } \note{ -the technically present root tree node is excluded from the summary returned by -both \code{make_row_df} and \code{make_col_df} (see \code{rtables::make_col_df}), as it is simply the +The technically present root tree node is excluded from the summary returned by +both \code{make_row_df} and \code{make_col_df} (see \code{\link[rtables:make_col_df]{rtables::make_col_df()}}), as it is simply the row/column structure of \code{tt} and thus not useful for pathing or pagination. } diff --git a/man/gen_args.Rd b/man/gen_args.Rd index a965d0de3..b5cf1e24c 100644 --- a/man/gen_args.Rd +++ b/man/gen_args.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/argument_conventions.R \name{gen_args} \alias{gen_args} -\title{General Argument Conventions} +\title{General argument conventions} \usage{ gen_args( df, @@ -33,90 +33,74 @@ gen_args( ) } \arguments{ -\item{df}{dataset (\code{data.frame} or \code{tibble})} +\item{df}{(\code{data.frame} or \code{tibble})\cr dataset.} -\item{alt_counts_df}{dataset (\code{data.frame} or \code{tibble}). Alternative full data -the rtables framework will use (\emph{only}) when calculating column -counts.} +\item{alt_counts_df}{(\code{data.frame} or \code{tibble})\cr alternative full dataset the rtables framework will use +\emph{only} when calculating column counts.} -\item{spl}{A Split object defining a partitioning or analysis/tabulation of -the data.} +\item{spl}{(\code{Split})\cr a \code{Split} object defining a partitioning or analysis/tabulation of the data.} -\item{pos}{numeric. Which top-level set of nested splits should the new -layout feature be added to. Defaults to the current} +\item{pos}{(\code{numeric})\cr which top-level set of nested splits should the new layout feature be added to. Defaults +to the current split.} -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{tr}{\code{TableRow} (or related class). A \code{TableRow} object representing a -single row within a populated table.} +\item{tr}{(\code{TableRow} or related class)\cr a \code{TableRow} object representing a single row within a populated table.} -\item{verbose}{logical(1). Should extra debugging messages be shown. Defaults -to \code{FALSE}.} +\item{verbose}{(\code{flag})\cr whether additional information should be displayed to the user. Defaults to \code{FALSE}.} -\item{colwidths}{numeric vector. Column widths for use with vertical pagination.} +\item{colwidths}{(\code{numeric})\cr a vector of column widths for use in vertical pagination.} -\item{obj}{ANY. The object for the accessor to access or modify} +\item{obj}{(\code{ANY})\cr the object for the accessor to access or modify.} -\item{x}{An object} +\item{x}{(\code{ANY})\cr an object.} -\item{value}{The new value} +\item{value}{(\code{ANY})\cr the new value.} -\item{object}{The object to modify in-place} +\item{object}{(\code{ANY})\cr the object to modify in place.} -\item{path}{character. A vector path for a position within the structure of a -\code{tabletree}. Each element represents a subsequent choice amongst the children -of the previous choice.} +\item{path}{(\code{character})\cr a vector path for a position within the structure of a \code{TableTree}. Each element +represents a subsequent choice amongst the children of the previous choice.} -\item{label}{character(1). A label (not to be confused with the name) for the -object/structure.} +\item{label}{(\code{string})\cr a label (not to be confused with the name) for the object/structure.} -\item{label_pos}{character(1). Location the variable label should be -displayed, Accepts \code{"hidden"} (default for non-analyze row splits), \code{"visible"}, -\code{"topleft"}, and - for analyze splits only - \code{"default"}. For analyze calls, -\code{"default"} indicates that the variable should be visible if and only if -multiple variables are analyzed at the same level of nesting.} +\item{label_pos}{(\code{string})\cr location where the variable label should be displayed. Accepts \code{"hidden"} +(default for non-analyze row splits), \code{"visible"}, \code{"topleft"}, and \code{"default"} (for analyze splits only). For +\code{analyze} calls, \code{"default"} indicates that the variable should be visible if and only if multiple variables are +analyzed at the same level of nesting.} -\item{cvar}{character(1). The variable, if any, which the content function -should accept. Defaults to NA.} +\item{cvar}{(\code{string})\cr the variable, if any, that the content function should accept. Defaults to \code{NA}.} -\item{topleft}{character. Override values for the "top left" material to be -displayed during printing.} +\item{topleft}{(\code{character})\cr override values for the "top left" material to be displayed during printing.} -\item{page_prefix}{character(1). Prefix, to be appended with the split value, -when forcing pagination between the children of this split/table} +\item{page_prefix}{(\code{string})\cr prefix to be appended with the split value when forcing pagination between +the children of a split/table.} -\item{hsep}{character(1). Set of character(s) to be repeated as the separator -between the header and body of the table when rendered as text. Defaults to -a connected horizontal line (unicode 2014) in locals that use a UTF -charset, and to \code{-} elsewhere (with a once per session warning). See -\code{\link[formatters:default_horizontal_sep]{formatters::set_default_hsep()}} for further information.} +\item{hsep}{(\code{string})\cr set of characters to be repeated as the separator between the header and body of +the table when rendered as text. Defaults to a connected horizontal line (unicode 2014) in locals that use a UTF +charset, and to \code{-} elsewhere (with a once per session warning). See \code{\link[formatters:default_horizontal_sep]{formatters::set_default_hsep()}} for further +information.} -\item{indent_size}{numeric(1). Number of spaces to use per indent level. -Defaults to 2} +\item{indent_size}{(\code{numeric(1)})\cr number of spaces to use per indent level. Defaults to 2.} -\item{section_div}{character(1). String which should be repeated as a section -divider after each group defined by this split instruction, or -\code{NA_character_} (the default) for no section divider.} +\item{section_div}{(\code{string})\cr string which should be repeated as a section divider after each group defined +by this split instruction, or \code{NA_character_} (the default) for no section divider.} -\item{na_str}{character(1). String that should be displayed when the value of \code{x} is missing. -Defaults to \code{"NA"}.} +\item{na_str}{(\code{string})\cr string that should be displayed when the value of \code{x} is missing. Defaults to \code{"NA"}.} -\item{inset}{numeric(1). Number of spaces to inset the table header, table -body, referential footnotes, and main_footer, as compared to alignment -of title, subtitle, and provenance footer. Defaults to 0 (no inset).} +\item{inset}{(\code{numeric(1)})\cr number of spaces to inset the table header, table body, referential footnotes, and +main_footer, as compared to alignment of title, subtitle, and provenance footer. Defaults to 0 (no inset).} -\item{table_inset}{numeric(1). Number of spaces to inset the table header, table -body, referential footnotes, and main_footer, as compared to alignment -of title, subtitle, and provenance footer. Defaults to 0 (no inset).} +\item{table_inset}{(\code{numeric(1)})\cr number of spaces to inset the table header, table body, referential footnotes, +and main footer, as compared to alignment of title, subtitles, and provenance footer. Defaults to 0 (no inset).} -\item{\dots}{Passed on to methods or tabulation functions.} +\item{...}{additional parameters passed to methods or tabulation functions.} } \value{ -NULL (this is an argument template dummy function) +No return value. } \description{ -General Argument Conventions +General argument conventions } \seealso{ Other conventions: @@ -126,3 +110,4 @@ Other conventions: \code{\link{sf_args}()} } \concept{conventions} +\keyword{internal} diff --git a/man/gfc.Rd b/man/gfc.Rd index 5d3eaee99..3755f424d 100644 --- a/man/gfc.Rd +++ b/man/gfc.Rd @@ -11,7 +11,7 @@ \alias{get_cell_aligns,ElementaryTable-method} \alias{get_cell_aligns,TableRow-method} \alias{get_cell_aligns,LabelRow-method} -\title{get formatted cells} +\title{Get formatted cells} \usage{ get_formatted_cells(obj, shell = FALSE) @@ -34,16 +34,16 @@ get_cell_aligns(obj) \S4method{get_cell_aligns}{LabelRow}(obj) } \arguments{ -\item{obj}{ANY. The object for the accessor to access or modify} +\item{obj}{(\code{ANY})\cr the object for the accessor to access or modify.} -\item{shell}{logical(1). Should the formats themselves be returned instead of the -values with formats applied. Defaults to \code{FALSE}.} +\item{shell}{(\code{flag})\cr whether the formats themselves should be returned instead of the values with formats +applied. Defaults to \code{FALSE}.} } \value{ -the formatted print-strings for all (body) cells in \code{obj}. +The formatted print-strings for all (body) cells in \code{obj}. } \description{ -get formatted cells +Get formatted cells } \examples{ library(dplyr) @@ -60,4 +60,5 @@ tbl <- basic_table() \%>\% build_table(iris2) get_formatted_cells(tbl) + } diff --git a/man/head_tail.Rd b/man/head_tail.Rd index 7b7528acc..4a454ba89 100644 --- a/man/head_tail.Rd +++ b/man/head_tail.Rd @@ -48,19 +48,17 @@ tail(x, ...) length(dim(x))}) select all indices in that dimension. Must contain at least one non-missing value.} -\item{keep_topleft}{logical(1). If \code{TRUE} (the default), -top_left material for the table will be carried over to the +\item{keep_topleft}{(\code{flag})\cr if \code{TRUE} (the default), top_left material for the table will be carried over to the subset.} -\item{keep_titles}{logical(1). If \code{TRUE} (the default), -all title material for the table will be carried over to the +\item{keep_titles}{(\code{flag})\cr if \code{TRUE} (the default), all title material for the table will be carried over to the subset.} -\item{keep_footers}{logical(1). If \code{TRUE}, all footer material for the table -will be carried over to the subset. It defaults to \code{keep_titles}.} +\item{keep_footers}{(\code{flag})\cr if \code{TRUE}, all footer material for the table will be carried over to the subset. It +defaults to \code{keep_titles}.} -\item{reindex_refs}{logical(1). Defaults to \code{FALSE}. If \code{TRUE}, -referential footnotes will be reindexed for the subset.} +\item{reindex_refs}{(\code{flag})\cr defaults to \code{FALSE}. If \code{TRUE}, referential footnotes will be reindexed for the +subset.} } \description{ Head and tail methods diff --git a/man/horizontal_sep.Rd b/man/horizontal_sep.Rd index 625bc2a3e..0f687f38c 100644 --- a/man/horizontal_sep.Rd +++ b/man/horizontal_sep.Rd @@ -19,14 +19,16 @@ horizontal_sep(obj) <- value \S4method{horizontal_sep}{TableRow}(obj) <- value } \arguments{ -\item{obj}{ANY. The object for the accessor to access or modify} +\item{obj}{(\code{ANY})\cr the object for the accessor to access or modify.} -\item{value}{character(1). String to use as new header/body separator.} +\item{value}{(\code{string})\cr string to use as new header/body separator.} } \value{ -for \code{horizontal_sep} the string acting as the header separator. -for \verb{horizontal_sep<-}, the \code{obj}, with the new header separator -applied recursively to it and all its subtables. +\itemize{ +\item \code{horizontal_sep} returns the string acting as the header separator. +\item \verb{horizontal_sep<-} returns \code{obj}, with the new header separator applied recursively to it and all its +subtables. +} } \description{ Access or recursively set header-body separator for tables diff --git a/man/in_rows.Rd b/man/in_rows.Rd index c96bac2ca..7ad68b0e9 100644 --- a/man/in_rows.Rd +++ b/man/in_rows.Rd @@ -18,38 +18,33 @@ in_rows( ) } \arguments{ -\item{...}{single row defining expressions} +\item{...}{single row defining expressions.} -\item{.list}{list. list cell content, usually \code{rcells}, the \code{.list} is -concatenated to \code{...}} +\item{.list}{(\code{list})\cr list cell content (usually \code{rcells}). The \code{.list} is concatenated to \code{...}.} -\item{.names}{character or NULL. Names of the returned list/structure.} +\item{.names}{(\code{character} or \code{NULL})\cr names of the returned list/structure.} -\item{.labels}{character or NULL. labels for the defined rows} +\item{.labels}{(\code{character} or \code{NULL})\cr labels for the defined rows.} -\item{.formats}{character or NULL. Formats for the values} +\item{.formats}{(\code{character} or \code{NULL})\cr formats for the values.} -\item{.indent_mods}{integer or NULL. Indent modifications for the defined -rows.} +\item{.indent_mods}{(\code{integer} or \code{NULL})\cr indent modifications for the defined rows.} -\item{.cell_footnotes}{list. Referential footnote messages to be associated -by name with \emph{cells}.} +\item{.cell_footnotes}{(\code{list})\cr referential footnote messages to be associated by name with \emph{cells}.} -\item{.row_footnotes}{list. Referential footnotes messages to be associated -by name with \emph{rows}.} +\item{.row_footnotes}{(\code{list})\cr referential footnotes messages to be associated by name with \emph{rows}.} -\item{.aligns}{character or NULL. Alignments for the cells. Standard for \code{NULL} -is \code{"center"}. See \code{\link[formatters:list_formats]{formatters::list_valid_aligns()}} for currently supported -alignments.} +\item{.aligns}{(\code{character} or \code{NULL})\cr alignments for the cells. Standard for \code{NULL} is \code{"center"}. +See \code{\link[formatters:list_formats]{formatters::list_valid_aligns()}} for currently supported alignments.} -\item{.format_na_strs}{character or NULL. NA strings for the cells} +\item{.format_na_strs}{(\code{character} or \code{NULL})\cr NA strings for the cells.} } \value{ -an \code{RowsVerticalSection} object (or \code{NULL}). The details of -this object should be considered an internal implementation detail. +A \code{RowsVerticalSection} object (or \code{NULL}). The details of this object should be considered an +internal implementation detail. } \description{ -define the cells that get placed into multiple rows in \code{afun} +Define the cells that get placed into multiple rows in \code{afun}. } \note{ In post-processing, referential footnotes can also be added using row and column diff --git a/man/indent.Rd b/man/indent.Rd index cc5d66ac3..337d505ab 100644 --- a/man/indent.Rd +++ b/man/indent.Rd @@ -7,10 +7,10 @@ indent(x, by = 1) } \arguments{ -\item{x}{\code{\link{rtable}} object} +\item{x}{(\code{VTableTree})\cr an \code{rtable} object.} -\item{by}{integer to increase indentation of rows. Can be negative. If final indentation is smaller than 0 then the -indentation is set to 0.} +\item{by}{(\code{integer})\cr number to increase indentation of rows by. Can be negative. If final indentation is +less than 0, the indentation is set to 0.} } \value{ \code{x} with its indent modifier incremented by \code{by}. diff --git a/man/indent_string.Rd b/man/indent_string.Rd index 4c9940a04..d3233e8b0 100644 --- a/man/indent_string.Rd +++ b/man/indent_string.Rd @@ -2,21 +2,21 @@ % Please edit documentation in R/tt_toString.R \name{indent_string} \alias{indent_string} -\title{Indent Strings} +\title{Indent strings} \usage{ indent_string(x, indent = 0, incr = 2, including_newline = TRUE) } \arguments{ -\item{x}{a character vector} +\item{x}{(\code{character})\cr a character vector.} -\item{indent}{a vector of length \code{length(x)} with non-negative integers} +\item{indent}{(\code{numeric})\cr a vector of non-negative integers of length \code{length(x)}.} -\item{incr}{non-negative integer: number of spaces per indent level} +\item{incr}{(\code{integer(1)})\cr a non-negative number of spaces per indent level.} -\item{including_newline}{boolean: should newlines also be indented} +\item{including_newline}{(\code{flag})\cr whether newlines should also be indented.} } \value{ -\code{x} indented by left-padding with \code{indent*incr} white-spaces. +\code{x}, indented with left-padding with \code{indent * incr} white-spaces. } \description{ Used in rtables to indent row names for the ASCII output. diff --git a/man/insert_row_at_path.Rd b/man/insert_row_at_path.Rd index 1874f2634..bb4ebe026 100644 --- a/man/insert_row_at_path.Rd +++ b/man/insert_row_at_path.Rd @@ -4,7 +4,7 @@ \alias{insert_row_at_path} \alias{insert_row_at_path,VTableTree,DataRow-method} \alias{insert_row_at_path,VTableTree,ANY-method} -\title{Insert Row at Path} +\title{Insert row at path} \usage{ insert_row_at_path(tt, path, value, after = FALSE) @@ -13,21 +13,19 @@ insert_row_at_path(tt, path, value, after = FALSE) \S4method{insert_row_at_path}{VTableTree,ANY}(tt, path, value) } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{path}{character. A vector path for a position within the structure of a -\code{tabletree}. Each element represents a subsequent choice amongst the children -of the previous choice.} +\item{path}{(\code{character})\cr a vector path for a position within the structure of a \code{TableTree}. Each element +represents a subsequent choice amongst the children of the previous choice.} -\item{value}{The new value} +\item{value}{(\code{ANY})\cr the new value.} -\item{after}{logical(1). Should \code{value} be added as a row directly before (\code{FALSE}, -the default) or after (\code{TRUE}) the row specified by \code{path}.} +\item{after}{(\code{flag})\cr whether \code{value} should be added as a row directly before (\code{FALSE}, the default) or after +(\code{TRUE}) the row specified by \code{path}.} } \description{ -Insert a row into an existing table directly before or directly after an existing -data (i.e., non-content and non-label) row, specified by its path. +Insert a row into an existing table directly before or directly after an existing data (i.e., non-content and +non-label) row, specified by its path. } \examples{ lyt <- basic_table() \%>\% @@ -47,7 +45,8 @@ tbl3 <- insert_row_at_path(tbl2, c("COUNTRY", "CHN", "AGE", "Mean"), after = TRUE ) tbl3 + } \seealso{ -\code{\link[=DataRow]{DataRow()}} \code{\link[=rrow]{rrow()}} +\code{\link[=DataRow]{DataRow()}}, \code{\link[=rrow]{rrow()}} } diff --git a/man/insert_rrow.Rd b/man/insert_rrow.Rd index fc9cf2611..6d8d11908 100644 --- a/man/insert_rrow.Rd +++ b/man/insert_rrow.Rd @@ -2,31 +2,29 @@ % Please edit documentation in R/tt_compatibility.R \name{insert_rrow} \alias{insert_rrow} -\title{[DEPRECATED] insert \code{rrows} at (before) a specific location} +\title{\strong{Deprecated:} Insert \code{rrow}s at (before) a specific location} \usage{ insert_rrow(tbl, rrow, at = 1, ascontent = FALSE) } \arguments{ -\item{tbl}{\code{rtable}} +\item{tbl}{(\code{VTableTree})\cr a \code{rtable} object.} -\item{rrow}{\code{rrow} to append to \code{rtable}} +\item{rrow}{(\code{TableRow})\cr an \code{rrow} to append to \code{tbl}.} -\item{at}{position into which to put the \code{rrow}, defaults to beginning (i.e. 1)} +\item{at}{(\code{integer(1)})\cr position into which to put the \code{rrow}, defaults to beginning (i.e. row 1).} -\item{ascontent}{logical. Currently ignored.} +\item{ascontent}{(\code{flag})\cr currently ignored.} } \value{ -A \code{TableTree} of the same specific class as \code{tbl} +A \code{TableTree} of the same specific class as \code{tbl}. } \description{ -This function is deprecated and will be removed in a future release of -\code{rtables}. Please use \code{\link{insert_row_at_path}} or -\code{\link{label_at_path}} instead. +This function is deprecated and will be removed in a future release of \code{rtables}. Please use +\code{\link[=insert_row_at_path]{insert_row_at_path()}} or \code{\link[=label_at_path]{label_at_path()}} instead. } \note{ -Label rows (i.e. a row with no data values, only a \code{row.name}) can only be -inserted at positions which do not already contain a label row when there -is a non-trivial nested row structure in \code{tbl} +Label rows (i.e. a row with no data values, only a \code{row.name}) can only be inserted at positions which do +not already contain a label row when there is a non-trivial nested row structure in \code{tbl}. } \examples{ o <- options(warn = 0) @@ -55,4 +53,5 @@ insert_rrow(tbl2, rrow("new row", 5, 6, 7)) insert_rrow(tbl2, rrow("new row", 5, 6, 7), at = 3) options(o) + } diff --git a/man/int_methods.Rd b/man/int_methods.Rd index 1920d9208..a34c1a74b 100644 --- a/man/int_methods.Rd +++ b/man/int_methods.Rd @@ -38,9 +38,6 @@ \alias{fix_dyncuts,PreDataTableLayouts-method} \alias{summarize_rows_inner} \alias{summarize_rows_inner,TableTree-method} -\alias{summarize_rows_inner,ElementaryTable-method} -\alias{summarize_rows_inner,TableRow-method} -\alias{summarize_rows_inner,LabelRow-method} \alias{table_structure_inner} \alias{str} \alias{str,VTableTree-method} @@ -48,6 +45,7 @@ \alias{table_structure_inner,ElementaryTable-method} \alias{table_structure_inner,TableRow-method} \alias{table_structure_inner,LabelRow-method} +\alias{int_methods} \alias{nrow,TableRow-method} \alias{ncol,TableRow-method} \alias{ncol,LabelRow-method} @@ -351,7 +349,7 @@ \alias{value_at,LabelRow-method} \alias{print,VTableTree-method} \alias{show,VTableTree-method} -\title{combine \code{SplitVector} objects} +\title{Combine \code{SplitVector} objects} \usage{ \S4method{c}{SplitVector}(x, ...) @@ -471,12 +469,6 @@ summarize_rows_inner(obj, depth = 0, indent = 0) \S4method{summarize_rows_inner}{TableTree}(obj, depth = 0, indent = 0) -\S4method{summarize_rows_inner}{ElementaryTable}(obj, depth = 0, indent = 0) - -\S4method{summarize_rows_inner}{TableRow}(obj, depth = 0, indent = 0) - -\S4method{summarize_rows_inner}{LabelRow}(obj, depth = 0, indent = 0) - table_structure_inner(obj, depth = 0, indent = 0, print_indent = 0) str(object, ...) @@ -1098,124 +1090,111 @@ spl_varnames(object) <- value \S4method{show}{VTableTree}(object) } \arguments{ -\item{x}{The object.} +\item{x}{(\code{ANY})\cr the object.} -\item{...}{Splits or \code{SplitVector} objects} +\item{...}{splits or \code{SplitVector} objects.} -\item{lyt}{layout object pre-data used for tabulation} +\item{lyt}{(\code{PreDataTableLayouts})\cr layout object pre-data used for tabulation.} -\item{spl}{Split. The split.} +\item{spl}{(\code{Split})\cr the split.} -\item{pos}{numeric(1). Intended for internal use.} +\item{pos}{(\code{numeric(1)})\cr intended for internal use.} -\item{cmpnd_fun}{function. Intended for internal use.} +\item{cmpnd_fun}{(\code{function})\cr intended for internal use.} -\item{constructor}{function.} +\item{constructor}{(\code{function})\cr constructor function.} -\item{label}{character(1). A label (not to be confused with the name) for the -object/structure.} +\item{label}{(\code{string})\cr a label (not to be confused with the name) for the object/structure.} -\item{cfun}{list/function/NULL. tabulation function(s) for creating content -rows. Must accept \code{x} or \code{df} as first parameter. Must accept -\code{labelstr} as the second argument. Can optionally accept all optional -arguments accepted by analysis functions. See \code{\link{analyze}}.} +\item{cfun}{(\code{list}, \code{function}, or \code{NULL})\cr tabulation function(s) for creating content rows. Must accept \code{x} +or \code{df} as first parameter. Must accept \code{labelstr} as the second argument. Can optionally accept all optional +arguments accepted by analysis functions. See \code{\link[=analyze]{analyze()}}.} -\item{child_labels}{string. One of \code{"default"}, \code{"visible"}, -\code{"hidden"}. What should the display behavior be for the labels (i.e. -label rows) of the children of this split. Defaults to \code{"default"} -which flags the label row as visible only if the child has 0 content rows.} +\item{child_labels}{(\code{string})\cr the display behavior for the labels (i.e. label rows) of the children of this +split. Accepts \code{"default"}, \code{"visible"}, and \code{"hidden"}. Defaults to \code{"default"} which flags the label row as +visible only if the child has 0 content rows.} -\item{cformat}{format spec. Format for content rows} +\item{cformat}{(\code{string}, \code{function}, or \code{list})\cr format for content rows.} -\item{cna_str}{character. NA string for use with \code{cformat} for content -table.} +\item{cna_str}{(\code{character})\cr NA string for use with \code{cformat} for content table.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} -\item{cvar}{character(1). The variable, if any, which the content function -should accept. Defaults to NA.} +\item{cvar}{(\code{string})\cr the variable, if any, that the content function should accept. Defaults to \code{NA}.} -\item{extra_args}{list. Extra arguments to be passed to the tabulation -function. Element position in the list corresponds to the children of this -split. Named elements in the child-specific lists are ignored if they do +\item{extra_args}{(\code{list})\cr extra arguments to be passed to the tabulation function. Element position in the list +corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do not match a formal argument of the tabulation function.} -\item{df}{dataset (\code{data.frame} or \code{tibble})} +\item{df}{(\code{data.frame} or \code{tibble})\cr dataset.} -\item{obj}{The object.} +\item{obj}{(\code{ANY})\cr the object.} -\item{depth}{depth in tree} +\item{depth}{(\code{numeric(1)})\cr depth in tree.} -\item{indent}{indent} +\item{indent}{(\code{numeric(1)})\cr indent.} -\item{print_indent}{indent for print} +\item{print_indent}{(\code{numeric(1)})\cr indent for printing.} -\item{object}{a table object} +\item{object}{(\code{VTableTree})\cr a table object.} -\item{max.level}{numeric(1). Passed to \code{utils::str}. Defaults to 3 for the -\code{VTableTree} method, unlike the underlying default of \code{NA}. \code{NA} is \emph{not} -appropriate for \code{VTableTree} objects.} +\item{max.level}{(\code{numeric(1)})\cr passed to \code{utils::str}. Defaults to 3 for the \code{VTableTree} method, unlike +the underlying default of \code{NA}. \code{NA} is \emph{not} appropriate for \code{VTableTree} objects.} -\item{value}{The new value} +\item{value}{(\code{ANY})\cr the new value.} -\item{nested}{boolean. Should this layout instruction be applied within the -existing layout structure \emph{if possible} (\code{TRUE}, the default) or as a -new top-level element (`FALSE). Ignored if it would nest a split underneath -analyses, which is not allowed.} +\item{nested}{(\code{logical})\cr whether this layout instruction should be applied within the existing layout structure +\emph{if possible} (\code{TRUE}, the default) or as a new top-level element (\code{FALSE}). Ignored if it would nest a split +underneath analyses, which is not allowed.} -\item{for_analyze}{logical(1).} +\item{for_analyze}{(\code{flag}) whether split is an analyze split.} -\item{format}{\code{FormatSpec}. Format associated with this split. Formats can be -declared via strings (\code{"xx.x"}) or function. In cases such as -\code{analyze} calls, they can character vectors or lists of functions.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr format associated with this split. Formats can be declared via +strings (\code{"xx.x"}) or function. In cases such as \code{analyze} calls, they can be character vectors or lists of +functions. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for a list of all available format strings.} -\item{na_str}{character(1). String that should be displayed when the value of \code{x} is missing. -Defaults to \code{"NA"}.} +\item{na_str}{(\code{string})\cr string that should be displayed when the value of \code{x} is missing. Defaults to \code{"NA"}.} -\item{override}{logical(1).} +\item{override}{(\code{flag})\cr whether to override attribute.} -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{incl.cont}{logical. Include rows from content tables within the tree. Defaults to \code{TRUE}} +\item{incl.cont}{(\code{flag})\cr whether to include rows from content tables within the tree. Defaults to \code{TRUE}.} -\item{add.labrows}{logical. Include label rows. Defaults to \code{FALSE}} +\item{add.labrows}{(\code{flag})\cr whether to include label rows. Defaults to \code{FALSE}.} -\item{mode}{character(1). Passed on to \code{\link[base]{as.vector}}} +\item{mode}{(\code{string})\cr passed on to \code{\link[=as.vector]{as.vector()}}.} -\item{rowpath}{character or NULL. Path within row structure. \code{NULL} -indicates the footnote should go on the column rather than cell.} +\item{rowpath}{(\code{character} or \code{NULL})\cr path within row structure. \code{NULL} indicates the footnote should +go on the column rather than cell.} -\item{colpath}{character or NULL. Path within column structure. \code{NULL} -indicates footnote should go on the row rather than cell} +\item{colpath}{(\code{character} or \code{NULL})\cr path within column structure. \code{NULL} indicates footnote should go +on the row rather than cell.} -\item{reset_idx}{logical(1). Should the numbering for referential footnotes -be immediately recalculated. Defaults to TRUE.} +\item{reset_idx}{(\code{flag})\cr whether the numbering for referential footnotes should be immediately +recalculated. Defaults to \code{TRUE}.} -\item{y}{Second element to be \code{rbound} via \code{rbind2}} +\item{y}{(\code{ANY})\cr second element to be row-bound via \code{rbind2}.} -\item{path}{character. A vector path for a position within the structure of a -\code{tabletree}. Each element represents a subsequent choice amongst the children -of the previous choice.} +\item{path}{(\code{character})\cr a vector path for a position within the structure of a \code{TableTree}. Each element +represents a subsequent choice amongst the children of the previous choice.} -\item{i}{index} +\item{i}{(\code{numeric(1)})\cr index.} -\item{j}{index} +\item{j}{(\code{numeric(1)})\cr index.} -\item{drop}{logical(1). Should the value in the cell be returned if one -cell is selected by the combination of \code{i} and \code{j}. It is not possible -to return a vector of values. To do so please consider using \code{\link[=cell_values]{cell_values()}}. -Defaults to \code{FALSE}.} +\item{drop}{(\code{flag})\cr whether the value in the cell should be returned if one cell is selected by the +combination of \code{i} and \code{j}. It is not possible to return a vector of values. To do so please consider using +\code{\link[=cell_values]{cell_values()}}. Defaults to \code{FALSE}.} } \value{ Various, but should be considered implementation details. } \description{ -These are internal methods that are documented only to satisfy -\verb{R CMD check}. End users should pay no attention to this documentation. +These are internal methods that are documented only to satisfy \verb{R CMD check}. End users should pay no +attention to this documentation. } \examples{ library(dplyr) @@ -1238,5 +1217,6 @@ tbl <- build_table(lyt, iris2) indent_mod(tbl) indent_mod(tbl) <- 1L tbl + } \keyword{internal} diff --git a/man/is_rtable.Rd b/man/is_rtable.Rd index 84d426ee6..1e78c884b 100644 --- a/man/is_rtable.Rd +++ b/man/is_rtable.Rd @@ -7,14 +7,15 @@ is_rtable(x) } \arguments{ -\item{x}{an object} +\item{x}{(\code{ANY})\cr an object.} } \value{ -\code{TRUE} if \code{x} is a formal Table object, \code{FALSE} otherwise. +\code{TRUE} if \code{x} is a formal \code{TableTree} object, \code{FALSE} otherwise. } \description{ Check if an object is a valid \code{rtable} } \examples{ is_rtable(build_table(basic_table(), iris)) + } diff --git a/man/label_at_path.Rd b/man/label_at_path.Rd index a1313b42a..7d5eba5f4 100644 --- a/man/label_at_path.Rd +++ b/man/label_at_path.Rd @@ -3,41 +3,34 @@ \name{label_at_path} \alias{label_at_path} \alias{label_at_path<-} -\title{Label at Path} +\title{Label at path} \usage{ label_at_path(tt, path) label_at_path(tt, path) <- value } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{path}{character. A vector path for a position within the structure of a -\code{tabletree}. Each element represents a subsequent choice amongst the children -of the previous choice.} +\item{path}{(\code{character})\cr a vector path for a position within the structure of a \code{TableTree}. Each element +represents a subsequent choice amongst the children of the previous choice.} -\item{value}{The new value} +\item{value}{(\code{ANY})\cr the new value.} } \description{ -Gets or sets the label at a path +Accesses or sets the label at a path. } \details{ -If \code{path} resolves to a single row, the label for that row -is retrieved or set. If, instead, \code{path} resolves to a subtable, -the text for the row-label associated with that path is retrieved -or set. In the subtable case, if the label text is set to a non-NA -value, the \code{labelrow} will be set to visible, even if it was not before. -Similarly, if the label row text for a subtable is set to NA, -the label row will bet set to non-visible, so the row will not +If \code{path} resolves to a single row, the label for that row is retrieved or set. If, instead, \code{path} resolves to a +subtable, the text for the row-label associated with that path is retrieved or set. In the subtable case, if the +label text is set to a non-\code{NA} value, the \code{labelrow} will be set to visible, even if it was not before. Similarly, +if the label row text for a subtable is set to \code{NA}, the label row will bet set to non-visible, so the row will not appear at all when the table is printed. } \note{ -When changing the row labels for content rows, it is important to -path all the way to the \emph{row}. Paths ending in \code{"@content"} will -not exhibit the behavior you want, and are thus an error. See -\code{\link{row_paths}} for help determining the full paths to content -rows. +When changing the row labels for content rows, it is important to path all the way to the \emph{row}. Paths +ending in \code{"@content"} will not exhibit the behavior you want, and are thus an error. See \code{\link[=row_paths]{row_paths()}} for help +determining the full paths to content rows. } \examples{ lyt <- basic_table() \%>\% @@ -50,4 +43,5 @@ label_at_path(tbl, c("COUNTRY", "CHN")) label_at_path(tbl, c("COUNTRY", "USA")) <- "United States" tbl + } diff --git a/man/length-CellValue-method.Rd b/man/length-CellValue-method.Rd index c1e12ab48..9e3c662dc 100644 --- a/man/length-CellValue-method.Rd +++ b/man/length-CellValue-method.Rd @@ -7,10 +7,10 @@ \S4method{length}{CellValue}(x) } \arguments{ -\item{x}{x.} +\item{x}{(\code{CellValue})\cr a \code{CellValue} object.} } \value{ -Always returns \code{1L} +Always returns \code{1L}. } \description{ Length of a Cell value diff --git a/man/list_wrap.Rd b/man/list_wrap.Rd index 64eb5ec47..eed81fbf0 100644 --- a/man/list_wrap.Rd +++ b/man/list_wrap.Rd @@ -3,32 +3,28 @@ \name{list_wrap_x} \alias{list_wrap_x} \alias{list_wrap_df} -\title{Returns a function that coerces the return values of f to a list} +\title{Returns a function that coerces the return values of a function to a list} \usage{ list_wrap_x(f) list_wrap_df(f) } \arguments{ -\item{f}{The function to wrap.} +\item{f}{(\code{function})\cr the function to wrap.} } \value{ -A function which calls \code{f} and converts the result to a list of -\code{CellValue} objects. +A function that returns a list of \code{CellValue} objects. } \description{ -Returns a function that coerces the return values of f to a list +Returns a function that coerces the return values of a function to a list } \details{ -\code{list_wrap_x} generates a wrapper which takes \code{x} as its -first argument, while \code{list_wrap_df} generates an otherwise identical -wrapper function whose first argument is named \code{df}. +\code{list_wrap_x} generates a wrapper which takes \code{x} as its first argument, while \code{list_wrap_df} generates an +otherwise identical wrapper function whose first argument is named \code{df}. -We provide both because when using the functions as tabulation in -\code{\link{analyze}}, functions which take \code{df} as their first -argument are passed the full subset dataframe, while those which accept -anything else notably including \code{x} are passed only the relevant -subset of the variable being analyzed. +We provide both because when using the functions as tabulation in \code{\link[=analyze]{analyze()}}, functions which take \code{df} as +their first argument are passed the full subset data frame, while those which accept anything else notably +including \code{x} are passed only the relevant subset of the variable being analyzed. } \examples{ summary(iris$Sepal.Length) diff --git a/man/lyt_args.Rd b/man/lyt_args.Rd index a74556b68..2b15de846 100644 --- a/man/lyt_args.Rd +++ b/man/lyt_args.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/argument_conventions.R \name{lyt_args} \alias{lyt_args} -\title{Layouting Function Arg Conventions} +\title{Layouting function argument conventions} \usage{ lyt_args( lyt, @@ -52,161 +52,132 @@ lyt_args( ) } \arguments{ -\item{lyt}{layout object pre-data used for tabulation} +\item{lyt}{(\code{PreDataTableLayouts})\cr layout object pre-data used for tabulation.} -\item{var}{string, variable name} +\item{var}{(\code{string})\cr variable name.} -\item{vars}{character vector. Multiple variable names.} +\item{vars}{(\code{character})\cr vector of variable names.} -\item{label}{character(1). A label (not to be confused with the name) for the -object/structure.} +\item{label}{(\code{string})\cr a label (not to be confused with the name) for the object/structure.} -\item{labels_var}{string, name of variable containing labels to be displayed -for the values of \code{var}} +\item{labels_var}{(\code{string})\cr name of variable containing labels to be displayed for the values of \code{var}.} -\item{varlabels}{character vector. Labels for \code{vars}} +\item{varlabels}{(\code{character})\cr vector of labels for \code{vars}.} -\item{varnames}{character vector. Names for \code{vars} which will appear in -pathing. When \code{vars} are all unique this will be the variable names. -If not, these will be variable names with suffixes as necessary to enforce +\item{varnames}{(\code{character})\cr vector of names for \code{vars} which will appear in pathing. When \code{vars} are all +unique this will be the variable names. If not, these will be variable names with suffixes as necessary to enforce uniqueness.} -\item{split_format}{\code{FormatSpec}. Default format associated with the split -being created.} +\item{split_format}{(\code{string}, \code{function}, or \code{list})\cr default format associated with the split being created.} -\item{split_na_str}{character. NA string vector for use with \code{split_format}.} +\item{split_na_str}{(\code{character})\cr NA string vector for use with \code{split_format}.} -\item{nested}{boolean. Should this layout instruction be applied within the -existing layout structure \emph{if possible} (\code{TRUE}, the default) or as a -new top-level element (`FALSE). Ignored if it would nest a split underneath -analyses, which is not allowed.} +\item{nested}{(\code{logical})\cr whether this layout instruction should be applied within the existing layout structure +\emph{if possible} (\code{TRUE}, the default) or as a new top-level element (\code{FALSE}). Ignored if it would nest a split +underneath analyses, which is not allowed.} -\item{format}{\code{FormatSpec}. Format associated with this split. Formats can be -declared via strings (\code{"xx.x"}) or function. In cases such as -\code{analyze} calls, they can character vectors or lists of functions.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr format associated with this split. Formats can be declared via +strings (\code{"xx.x"}) or function. In cases such as \code{analyze} calls, they can be character vectors or lists of +functions. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for a list of all available format strings.} -\item{cfun}{list/function/NULL. tabulation function(s) for creating content -rows. Must accept \code{x} or \code{df} as first parameter. Must accept -\code{labelstr} as the second argument. Can optionally accept all optional -arguments accepted by analysis functions. See \code{\link{analyze}}.} +\item{cfun}{(\code{list}, \code{function}, or \code{NULL})\cr tabulation function(s) for creating content rows. Must accept \code{x} +or \code{df} as first parameter. Must accept \code{labelstr} as the second argument. Can optionally accept all optional +arguments accepted by analysis functions. See \code{\link[=analyze]{analyze()}}.} -\item{cformat}{format spec. Format for content rows} +\item{cformat}{(\code{string}, \code{function}, or \code{list})\cr format for content rows.} -\item{cna_str}{character. NA string for use with \code{cformat} for content -table.} +\item{cna_str}{(\code{character})\cr NA string for use with \code{cformat} for content table.} -\item{split_fun}{function/NULL. custom splitting function See -\code{\link{custom_split_funs}}} +\item{split_fun}{(\code{function} or \code{NULL})\cr custom splitting function. See \link{custom_split_funs}.} -\item{split_name}{string. Name associated with this split (for pathing, etc)} +\item{split_name}{(\code{string})\cr name associated with the split (for pathing, etc.).} -\item{split_label}{string. Label string to be associated with the table -generated by the split. Not to be confused with labels assigned to each -child (which are based on the data and type of split during tabulation).} +\item{split_label}{(\code{string})\cr label to be associated with the table generated by the split. Not to be confused +with labels assigned to each child (which are based on the data and type of split during tabulation).} -\item{afun}{function. Analysis function, must take \code{x} or \code{df} as -its first parameter. Can optionally take other parameters which will be -populated by the tabulation framework. See Details in -\code{\link{analyze}}.} +\item{afun}{(\code{function})\cr analysis function. Must accept \code{x} or \code{df} as its first parameter. Can optionally take +other parameters which will be populated by the tabulation framework. See Details in \code{\link[=analyze]{analyze()}}.} -\item{inclNAs}{boolean. Should observations with NA in the \code{var} -variable(s) be included when performing this analysis. Defaults to -\code{FALSE}} +\item{inclNAs}{(\code{logical})\cr whether NA observations in the \code{var} variable(s) should be included when performing +the analysis. Defaults to \code{FALSE}.} -\item{valorder}{character vector. Order that the split children should appear -in resulting table.} +\item{valorder}{(\code{character})\cr the order that the split children should appear in resulting table.} -\item{ref_group}{character. Value of \code{var} to be taken as the -ref_group/control to be compared against.} +\item{ref_group}{(\code{character})\cr value of \code{var} to be taken as the \code{ref_group}/control to be compared against.} -\item{compfun}{function/string. The comparison function which accepts the -analysis function outputs for two different partitions and returns a single -value. Defaults to subtraction. If a string, taken as the name of a +\item{compfun}{(\code{function} or \code{string})\cr the comparison function which accepts the analysis function outputs for +two different partitions and returns a single value. Defaults to subtraction. If a string, taken as the name of a function.} -\item{label_fstr}{string. An \code{sprintf} style format string containing. For -non-comparison splits, it can contain up to one \code{"\%s"} which takes -the current split value and generates the row/column label. -Comparison-based splits it can contain up to two \code{"\%s"}.} +\item{label_fstr}{(\code{string})\cr a \code{sprintf} style format string. For non-comparison splits, it can contain up to +one \code{"\\\%s"} which takes the current split value and generates the row/column label. For comparison-based splits +it can contain up to two \code{"\\\%s"}.} -\item{child_labels}{string. One of \code{"default"}, \code{"visible"}, -\code{"hidden"}. What should the display behavior be for the labels (i.e. -label rows) of the children of this split. Defaults to \code{"default"} -which flags the label row as visible only if the child has 0 content rows.} +\item{child_labels}{(\code{string})\cr the display behavior for the labels (i.e. label rows) of the children of this +split. Accepts \code{"default"}, \code{"visible"}, and \code{"hidden"}. Defaults to \code{"default"} which flags the label row as +visible only if the child has 0 content rows.} -\item{extra_args}{list. Extra arguments to be passed to the tabulation -function. Element position in the list corresponds to the children of this -split. Named elements in the child-specific lists are ignored if they do +\item{extra_args}{(\code{list})\cr extra arguments to be passed to the tabulation function. Element position in the list +corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do not match a formal argument of the tabulation function.} -\item{name}{character(1). Name of the split/table/row being created. Defaults -to same as the corresponding label, but is not required to be.} +\item{name}{(\code{string})\cr name of the split/table/row being created. Defaults to the value of the +corresponding label, but is not required to be.} -\item{cuts}{numeric. Cuts to use} +\item{cuts}{(\code{numeric})\cr cuts to use.} -\item{cutlabels}{character (or NULL). Labels for the cuts} +\item{cutlabels}{(\code{character} or \code{NULL})\cr labels for the cuts.} -\item{cutfun}{function. Function which accepts the \emph{full vector} of -\code{var} values and returns cut points to be used (via \code{cut}) when -splitting data during tabulation} +\item{cutfun}{(\code{function})\cr function which accepts the \emph{full vector} of \code{var} values and returns cut points to be +used (via \code{cut}) when splitting data during tabulation.} -\item{cutlabelfun}{function. Function which returns either labels for the -cuts or NULL when passed the return value of \code{cutfun}} +\item{cutlabelfun}{(\code{function})\cr function which returns either labels for the cuts or \code{NULL} when passed the +return value of \code{cutfun}.} -\item{cumulative}{logical. Should the cuts be treated as cumulative. Defaults -to \code{FALSE}} +\item{cumulative}{(\code{flag})\cr whether the cuts should be treated as cumulative. Defaults to \code{FALSE}.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} -\item{show_labels}{character(1). Should the variable labels for corresponding -to the variable(s) in \code{vars} be visible in the resulting table.} +\item{show_labels}{(\code{string})\cr whether the variable labels corresponding to the variable(s) in \code{vars} +should be visible in the resulting table.} -\item{label_pos}{character(1). Location the variable label should be -displayed, Accepts \code{"hidden"} (default for non-analyze row splits), \code{"visible"}, -\code{"topleft"}, and - for analyze splits only - \code{"default"}. For analyze calls, -\code{"default"} indicates that the variable should be visible if and only if -multiple variables are analyzed at the same level of nesting.} +\item{label_pos}{(\code{string})\cr location where the variable label should be displayed. Accepts \code{"hidden"} +(default for non-analyze row splits), \code{"visible"}, \code{"topleft"}, and \code{"default"} (for analyze splits only). For +\code{analyze} calls, \code{"default"} indicates that the variable should be visible if and only if multiple variables are +analyzed at the same level of nesting.} -\item{var_labels}{character. Variable labels for 1 or more variables} +\item{var_labels}{(\code{character})\cr vector of labels for one or more variables.} -\item{cvar}{character(1). The variable, if any, which the content function -should accept. Defaults to NA.} +\item{cvar}{(\code{string})\cr the variable, if any, that the content function should accept. Defaults to \code{NA}.} -\item{table_names}{character. Names for the tables representing each atomic -analysis. Defaults to \code{var}.} +\item{table_names}{(\code{character})\cr names for the tables representing each atomic analysis. Defaults to \code{var}.} -\item{topleft}{character. Override values for the "top left" material to be -displayed during printing.} +\item{topleft}{(\code{character})\cr override values for the "top left" material to be displayed during printing.} -\item{align}{character(1) or \code{NULL}. Alignment the value should be rendered with. -It defaults to \code{"center"} if \code{NULL} is used. See \code{\link[formatters:list_formats]{formatters::list_valid_aligns()}} -for currently supported alignments.} +\item{align}{(\code{string} or \code{NULL})\cr alignment the value should be rendered with. Defaults to \code{"center"} if +\code{NULL} is used. See \code{\link[formatters:list_formats]{formatters::list_valid_aligns()}} for all currently supported alignments.} -\item{page_by}{logical(1). Should pagination be forced between different -children resulting form this split. An error will rise if the selected split -does not contain at least one value that is not \code{NA}.} +\item{page_by}{(\code{flag})\cr whether pagination should be forced between different children resulting from this +split. An error will occur if the selected split does not contain at least one value that is not \code{NA}.} -\item{page_prefix}{character(1). Prefix, to be appended with the split value, -when forcing pagination between the children of this split/table} +\item{page_prefix}{(\code{string})\cr prefix to be appended with the split value when forcing pagination between +the children of a split/table.} -\item{format_na_str}{character(1). String which should be displayed when -formatted if this cell's value(s) are all NA.} +\item{format_na_str}{(\code{string})\cr string which should be displayed when formatted if this cell's value(s) +are all \code{NA}.} -\item{section_div}{character(1). String which should be repeated as a section -divider after each group defined by this split instruction, or -\code{NA_character_} (the default) for no section divider.} +\item{section_div}{(\code{string})\cr string which should be repeated as a section divider after each group defined +by this split instruction, or \code{NA_character_} (the default) for no section divider.} -\item{na_str}{character(1). String that should be displayed when the value of \code{x} is missing. -Defaults to \code{"NA"}.} +\item{na_str}{(\code{string})\cr string that should be displayed when the value of \code{x} is missing. Defaults to \code{"NA"}.} } \value{ -NULL (this is an argument template dummy function) +No return value. } \description{ -Layouting Function Arg Conventions +Layouting function argument conventions } \seealso{ Other conventions: @@ -216,3 +187,4 @@ Other conventions: \code{\link{sf_args}()} } \concept{conventions} +\keyword{internal} diff --git a/man/make_afun.Rd b/man/make_afun.Rd index 6403c27c4..676727f03 100644 --- a/man/make_afun.Rd +++ b/man/make_afun.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/tt_afun_utils.R \name{make_afun} \alias{make_afun} -\title{Create custom analysis function wrapping existing function} +\title{Create a custom analysis function wrapping an existing function} \usage{ make_afun( fun, @@ -17,51 +17,40 @@ make_afun( ) } \arguments{ -\item{fun}{function. The function to be wrapped in a new customized analysis -fun. Should return named list.} +\item{fun}{(\code{function})\cr the function to be wrapped in a new customized analysis function. +\code{fun} should return a named \code{list}.} -\item{.stats}{character. Names of elements to keep from \code{fun}'s full -output.} +\item{.stats}{(\code{character})\cr names of elements to keep from \code{fun}'s full output.} -\item{.formats}{ANY. vector/list of formats to override any defaults applied -by \code{fun}.} +\item{.formats}{(\code{ANY})\cr vector or list of formats to override any defaults applied by \code{fun}.} -\item{.labels}{character. Vector of labels to override defaults returned by -\code{fun}} +\item{.labels}{(\code{character})\cr vector of labels to override defaults returned by \code{fun}.} -\item{.indent_mods}{integer. Named vector of indent modifiers for the -generated rows.} +\item{.indent_mods}{(\code{integer})\cr named vector of indent modifiers for the generated rows.} -\item{.ungroup_stats}{character. Vector of names, which must match elements -of \code{.stats}} +\item{.ungroup_stats}{(\code{character})\cr vector of names, which must match elements of \code{.stats}.} -\item{.format_na_strs}{ANY. vector/list of \code{na} strings to override any -defaults applied by \code{fun}.} +\item{.format_na_strs}{(\code{ANY})\cr vector/list of \code{NA} strings to override any defaults applied by \code{fun}.} -\item{...}{dots. Additional arguments to \code{fun} which effectively become -new defaults. These can still be overridden by \code{extra_args} within a split.} +\item{...}{additional arguments to \code{fun} which effectively become new defaults. These can still be +overridden by \code{extra_args} within a split.} -\item{.null_ref_cells}{logical(1). Should cells for the reference column be -NULL-ed by the returned analysis function. Defaults to \code{TRUE} if -\code{fun} accepts \code{.in_ref_col} as a formal argument. Note this -argument occurs after \code{...} so it must be \emph{fully} specified by -name when set.} +\item{.null_ref_cells}{(\code{flag})\cr whether cells for the reference column should be \code{NULL}-ed by the +returned analysis function. Defaults to \code{TRUE} if \code{fun} accepts \code{.in_ref_col} as a formal argument. Note +this argument occurs after \code{...} so it must be \emph{fully} specified by name when set.} } \value{ -A function suitable for use in \code{\link{analyze}} with element -selection, reformatting, and relabeling performed automatically. +A function suitable for use in \code{\link[=analyze]{analyze()}} with element selection, reformatting, and relabeling +performed automatically. } \description{ -Create custom analysis function wrapping existing function +Create a custom analysis function wrapping an existing function } \note{ -setting \code{.ungroup_stats} to non-null changes the \emph{structure} -of the value(s) returned by \code{fun}, rather than just labeling -(\code{.labels}), formatting (\code{.formats}), and selecting amongst -(\code{.stats}) them. This means that subsequent \code{make_afun} calls to -customize the output further both can and must operate on the new -structure, \emph{NOT} the original structure returned by \code{fun}. See -the final pair of examples below. +Setting \code{.ungroup_stats} to non-\code{NULL} changes the \emph{structure} of the value(s) returned by \code{fun}, rather than +just labeling (\code{.labels}), formatting (\code{.formats}), and selecting amongst (\code{.stats}) them. This means that +subsequent \code{make_afun} calls to customize the output further both can and must operate on the new structure, +\emph{not} the original structure returned by \code{fun}. See the final pair of examples below. } \examples{ s_summary <- function(x) { @@ -90,8 +79,6 @@ a_summary2(x = iris$Sepal.Length) a_summary3 <- make_afun(a_summary, .formats = c(mean_sd = "(xx.xxx, xx.xxx)")) - - s_foo <- function(df, .N_col, a = 1, b = 2) { list( nrow_df = nrow(df), diff --git a/man/make_col_df.Rd b/man/make_col_df.Rd index c6d0b0eef..30a587d09 100644 --- a/man/make_col_df.Rd +++ b/man/make_col_df.Rd @@ -2,22 +2,19 @@ % Please edit documentation in R/tt_paginate.R \name{make_col_df} \alias{make_col_df} -\title{Column Layout Summary} +\title{Column layout summary} \usage{ make_col_df(tt, colwidths = NULL, visible_only = TRUE) } \arguments{ -\item{tt}{ANY. Object representing the table-like object to be summarized.} +\item{tt}{(\code{ANY})\cr object representing the table-like object to be summarized.} -\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). Should only visible aspects of the table structure be reflected in this summary. -Defaults to \code{TRUE}. May not be supported by all methods.} +\item{visible_only}{(\code{flag})\cr should only visible aspects of the table structure be reflected +in this summary. Defaults to \code{TRUE}. May not be supported by all methods.} } \description{ -Generate a structural summary of the columns of an -rtables table and return it as a data.frame. -} -\details{ -Used for Pagination +Used for pagination. Generate a structural summary of the columns of an \code{rtables} table and return it as a +\code{data.frame}. } diff --git a/man/make_col_row_df.Rd b/man/make_col_row_df.Rd index e0783bf24..d3256d3f0 100644 --- a/man/make_col_row_df.Rd +++ b/man/make_col_row_df.Rd @@ -3,20 +3,20 @@ \name{row_paths} \alias{row_paths} \alias{col_paths} -\title{Return List with Table Row/Col Paths} +\title{Get a list of table row/column paths} \usage{ row_paths(x) col_paths(x) } \arguments{ -\item{x}{an \code{rtable} object} +\item{x}{(\code{VTableTree})\cr an \code{rtable} object.} } \value{ -a list of paths to each row/column within \code{x} +A list of paths to each row/column within \code{x}. } \description{ -Return List with Table Row/Col Paths +Get a list of table row/column paths } \examples{ lyt <- basic_table() \%>\% @@ -33,6 +33,5 @@ cell_values(tbl, c("AGE", "Mean"), c("ARM", "B: Placebo")) } \seealso{ -\code{\link[=cell_values]{cell_values()}}, \code{\link{fnotes_at_path<-}}, -\code{\link[=row_paths_summary]{row_paths_summary()}}, \code{\link[=col_paths_summary]{col_paths_summary()}} +\code{\link[=cell_values]{cell_values()}}, \code{\link{fnotes_at_path<-}}, \code{\link[=row_paths_summary]{row_paths_summary()}}, \code{\link[=col_paths_summary]{col_paths_summary()}} } diff --git a/man/make_split_fun.Rd b/man/make_split_fun.Rd index bd297d6e9..a730c270c 100644 --- a/man/make_split_fun.Rd +++ b/man/make_split_fun.Rd @@ -2,78 +2,63 @@ % Please edit documentation in R/make_split_fun.R \name{make_split_fun} \alias{make_split_fun} -\title{Create a Custom Splitting Function} +\title{Create a custom splitting function} \usage{ make_split_fun(pre = list(), core_split = NULL, post = list()) } \arguments{ -\item{pre}{list. Zero or more functions which operate on the -incoming data and return a new data frame that should split via -\code{core_split}. They will be called on the data in the order they -appear in the list.} - -\item{core_split}{function or NULL. If not NULL, a function which -accepts the same arguments do_base_split does, and returns the -same type of named list. Custom functions which override this -behavior cannot be used in column splits.} - -\item{post}{list. Zero or more functions which should be called on -the list output by splitting.} +\item{pre}{(\code{list})\cr zero or more functions which operate on the incoming data and return a new data frame that +should split via \code{core_split}. They will be called on the data in the order they appear in the list.} + +\item{core_split}{(\code{function} or \code{NULL})\cr if non-\code{NULL}, a function which accepts the same arguments that +\code{do_base_split} does, and returns the same type of named list. Custom functions which override this behavior +cannot be used in column splits.} + +\item{post}{(\code{list})\cr zero or more functions which should be called on the list output by splitting.} } \value{ -A function for use as a custom split function. +A custom function that can be used as a split function. } \description{ -Create a Custom Splitting Function +Create a custom splitting function } \details{ -Custom split functions can be thought of as (up to) 3 different -types of manipulations of the splitting process +Custom split functions can be thought of as (up to) 3 different types of manipulations of the splitting process: \enumerate{ -\item Preprocessing of the incoming data to be split -\item (Row-splitting only) Customization of the core mapping of incoming data to facets, and -\item Postprocessing operations on the set of facets (groups) generated by the split. +\item Pre-processing of the incoming data to be split. +\item (Row-splitting only) Customization of the core mapping of incoming data to facets. +\item Post-processing operations on the set of facets (groups) generated by the split. } -This function provides an interface to create custom split -functions by implementing and specifying sets of operations in each -of those classes of customization independently. - -Preprocessing functions (1), must accept: \code{df}, \code{spl}, \code{vals}, -\code{labels}, and can optionally accept \code{.spl_context}. They then -manipulate \code{df} (the incoming data for the split) and return a -modified data.frame. This modified data.frame \emph{must} contain all -columns present in the incoming data.frame, but can add columns if -necessary (though we note that these new columns cannot be used in -the layout as split or analysis variables, because they will not be -present when validity checking is done). - -The preprocessing component is useful for things such as -manipulating factor levels, e.g., to trim unobserved ones or to -reorder levels based on observed counts, etc. - -Customization of core splitting (2) is currently only supported in -row splits. Core splitting functions override the fundamental -splitting procedure, and are only necessary in rare cases. These -must accept \code{spl}, \code{df}, \code{vals}, \code{labels}, and can optionally -accept \code{.spl_context}. They must return a named list with elements, -all of the same length, as follows: - \code{datasplit} (containing a -list of data.frames), - \code{values} containing values associated with -the facets, which must be \code{character} or \code{SplitValue} -objects. These values will appear in the paths of the resulting -table. - \code{labels} containing the character labels associated with -\code{values} - -Postprocessing functions (3) must accept the result of the core -split as their first argument (which as of writing can be -anything), in addition to \code{spl}, and \code{fulldf}, and can optionally -accept \code{.spl_context}. They must each return a modified version of -the same structure specified above for core splitting. - -In both the pre- and post-processing cases, multiple functions can -be specified. When this happens, they are applied sequentially, in -the order they appear in the list passed to the relevant argument -(\code{pre} and \code{post}, respectively). +This function provides an interface to create custom split functions by implementing and specifying sets of +operations in each of those classes of customization independently. + +Pre-processing functions (1), must accept: \code{df}, \code{spl}, \code{vals}, and \code{labels}, and can optionally accept +\code{.spl_context}. They then manipulate \code{df} (the incoming data for the split) and return a modified data frame. +This modified data frame \emph{must} contain all columns present in the incoming data frame, but can add columns if +necessary (though we note that these new columns cannot be used in the layout as split or analysis variables, +because they will not be present when validity checking is done). + +The preprocessing component is useful for things such as manipulating factor levels, e.g., to trim unobserved ones +or to reorder levels based on observed counts, etc. + +Customization of core splitting (2) is currently only supported in row splits. Core splitting functions override the +fundamental splitting procedure, and are only necessary in rare cases. These must accept \code{spl}, \code{df}, \code{vals}, and +\code{labels}, and can optionally accept \code{.spl_context}. They must return a named list with elements, all of the same +length, as follows: +\itemize{ +\item \code{datasplit}, containing a list of \code{data.frame} objects. +\item \code{values}, containing values associated with the facets, which must be \code{character} or \code{SplitValue} objects. +These values will appear in the paths of the resulting table. +\item \code{labels}, containing the character labels associated with \code{values} +} + +Post-processing functions (3) must accept the result of the core split as their first argument (which can be +anything), in addition to \code{spl}, and \code{fulldf}, and can optionally accept \code{.spl_context}. They must each return a +modified version of the same structure specified above for core splitting. + +In both the pre- and post-processing cases, multiple functions can be specified. When this happens, they are applied +sequentially, in the order they appear in the list passed to the relevant argument (\code{pre} and \code{post}, respectively). } \examples{ mysplitfun <- make_split_fun( @@ -81,7 +66,6 @@ mysplitfun <- make_split_fun( post = list(add_overall_facet("ALL", "All Arms")) ) - basic_table(show_colcounts = TRUE) \%>\% split_cols_by("ARM", split_fun = mysplitfun) \%>\% analyze("AGE") \%>\% @@ -135,10 +119,10 @@ lyt_silly <- basic_table() \%>\% analyze("AGE") silly_table <- build_table(lyt_silly, DM) silly_table + } \seealso{ -\link{custom_split_funs} for a more detailed discussion on what -custom split functions do. +\link{custom_split_funs} for a more detailed discussion on what custom split functions do. Other make_custom_split: \code{\link{add_combo_facet}()}, diff --git a/man/make_split_result.Rd b/man/make_split_result.Rd index afe7d5340..77363e4ee 100644 --- a/man/make_split_result.Rd +++ b/man/make_split_result.Rd @@ -10,34 +10,28 @@ make_split_result(values, datasplit, labels, extras = NULL) add_to_split_result(splres, values, datasplit, labels, extras = NULL) } \arguments{ -\item{values}{character or \code{list(SplitValue)}. The values associated -with each facet} +\item{values}{(\code{character} or \code{list(SplitValue)})\cr the values associated with each facet.} -\item{datasplit}{\code{list(data.frame)}. The facet data for each facet -generated in the split} +\item{datasplit}{(\code{list(data.frame)})\cr the facet data for each facet generated in the split.} -\item{labels}{character. The labels associated with each facet} +\item{labels}{(\code{character})\cr the labels associated with each facet.} -\item{extras}{NULL or list. Extra values associated with each of -the facets which will be passed to analysis functions applied -within the facet.} +\item{extras}{(\code{list} or \code{NULL})\cr extra values associated with each of the facets which will be passed to +analysis functions applied within the facet.} -\item{splres}{list. A list representing the result of splitting.} +\item{splres}{(\code{list})\cr a list representing the result of splitting.} } \value{ -a named list representing the facets generated by the split -with elements \code{values}, \code{datasplit}, and \code{labels}, which are -the same length and correspond to each other elementwise. +A named list representing the facets generated by the split with elements \code{values}, \code{datasplit}, and +\code{labels}, which are the same length and correspond to each other element-wise. } \description{ -These functions can be used to create or add to a split result in -functions which implement core splitting or post-processing within -a custom split function. +These functions can be used to create or add to a split result in functions which implement core splitting or +post-processing within a custom split function. } \details{ -These functions does various housekeeping to ensure that the split result -list is as the rtables internals expect it, most of which are not -relevant to end users. +These functions performs various housekeeping tasks to ensure that the split result list is as the rtables +internals expect it, most of which are not relevant to end users. } \examples{ splres <- make_split_result( @@ -51,6 +45,7 @@ splres2 <- add_to_split_result(splres, datasplit = list(med = mtcars[1:20, ]), labels = "kinda some data" ) + } \seealso{ Other make_custom_split: diff --git a/man/manual_cols.Rd b/man/manual_cols.Rd index 488d3ed8a..487a20ffa 100644 --- a/man/manual_cols.Rd +++ b/man/manual_cols.Rd @@ -7,16 +7,14 @@ manual_cols(..., .lst = list(...)) } \arguments{ -\item{\dots}{One or more vectors of levels to appear in the column space. If -more than one set of levels is given, the values of the second are nested -within each value of the first, and so on.} +\item{...}{one or more vectors of levels to appear in the column space. If more than one set of levels is given, +the values of the second are nested within each value of the first, and so on.} -\item{.lst}{A list of sets of levels, by default populated via -\code{list(...)}.} +\item{.lst}{(\code{list})\cr a list of sets of levels, by default populated via \code{list(...)}.} } \value{ -An \code{InstantiatedColumnInfo} object, suitable for use declaring the -column structure for a manually constructed table. +An \code{InstantiatedColumnInfo} object, suitable for declaring the column structure for a manually constructed +table. } \description{ Manual column declaration diff --git a/man/matrix_form-VTableTree-method.Rd b/man/matrix_form-VTableTree-method.Rd index b511ba77f..3ebb6a4c1 100644 --- a/man/matrix_form-VTableTree-method.Rd +++ b/man/matrix_form-VTableTree-method.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/tt_toString.R \name{matrix_form,VTableTree-method} \alias{matrix_form,VTableTree-method} -\title{Transform \code{rtable} to a list of matrices which can be used for outputting} +\title{Transform an \code{rtable} to a list of matrices which can be used for outputting} \usage{ \S4method{matrix_form}{VTableTree}( obj, @@ -12,44 +12,37 @@ ) } \arguments{ -\item{obj}{ANY. The object for the accessor to access or modify} +\item{obj}{(\code{ANY})\cr the object for the accessor to access or modify.} -\item{indent_rownames}{logical(1), if TRUE the column with the row names in -the \code{strings} matrix of has indented row names (strings pre-fixed)} +\item{indent_rownames}{(\code{flag})\cr if \code{TRUE}, the column with the row names in the \code{strings} matrix of the output +has indented row names (strings pre-fixed).} -\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 whether the matrix form generated should expand rows whose values contain +newlines into multiple 'physical' rows (as they will appear when rendered into ASCII). Defaults to \code{TRUE}.} -\item{indent_size}{numeric(1). Number of spaces to use per indent level. -Defaults to 2} +\item{indent_size}{(\code{numeric(1)})\cr number of spaces to use per indent level. Defaults to 2.} } \value{ A list with the following elements: \describe{ -\item{strings}{The content, as it should be printed, of the top-left -material, column headers, row labels , and cell values of \code{tt}} -\item{spans}{The column-span information for each print-string in the strings -matrix} -\item{aligns}{The text alignment for each print-string in the strings matrix} -\item{display}{Whether each print-string in the strings matrix should be -printed or not}. -\item{row_info}{the data.frame generated by \code{make_row_df}} +\item{\code{strings}}{The content, as it should be printed, of the top-left material, column headers, row labels, +and cell values of \code{tt}.} +\item{\code{spans}}{The column-span information for each print-string in the \code{strings} matrix.} +\item{\code{aligns}}{The text alignment for each print-string in the \code{strings} matrix.} +\item{\code{display}}{Whether each print-string in the strings matrix should be printed.} +\item{\code{row_info}}{The \code{data.frame} generated by \code{make_row_df}.} } -With an additional \code{nrow_header} attribute indicating the number of -pseudo "rows" the column structure defines. +With an additional \code{nrow_header} attribute indicating the number of pseudo "rows" that the column structure defines. } \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. +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{make_row_df} and cell values are determined using -\code{get_formatted_cells}. (Column labels are calculated using a -non-exported internal function. +The strings in the return object are defined as follows: row labels are those determined by \code{make_row_df} and cell +values are determined using \code{get_formatted_cells}. (Column labels are calculated using a non-exported internal +function. } \examples{ library(dplyr) @@ -71,4 +64,5 @@ lyt tbl <- build_table(lyt, iris2) matrix_form(tbl) + } diff --git a/man/names.Rd b/man/names.Rd index e58cba6fa..e2468bd10 100644 --- a/man/names.Rd +++ b/man/names.Rd @@ -16,7 +16,7 @@ \S4method{row.names}{VTableTree}(x) } \arguments{ -\item{x}{the object.} +\item{x}{(\code{TableTree})\cr the object.} } \value{ The column names of \code{x}, as defined in the details above. @@ -25,6 +25,6 @@ The column names of \code{x}, as defined in the details above. Names of a \code{TableTree} } \details{ -For \code{TableTrees} with more than one level of splitting in columns, the names are defined to be the top-level +For \code{TableTree}s with more than one level of splitting in columns, the names are defined to be the top-level split values repped out across the columns that they span. } diff --git a/man/no_info.Rd b/man/no_info.Rd index 0099faafb..5c5d10bc5 100644 --- a/man/no_info.Rd +++ b/man/no_info.Rd @@ -4,7 +4,7 @@ \alias{no_colinfo} \alias{no_colinfo,VTableNodeInfo-method} \alias{no_colinfo,InstantiatedColumnInfo-method} -\title{Exported for use in tern} +\title{Exported for use in \code{tern}} \usage{ no_colinfo(obj) @@ -13,11 +13,10 @@ no_colinfo(obj) \S4method{no_colinfo}{InstantiatedColumnInfo}(obj) } \arguments{ -\item{obj}{ANY. The object for the accessor to access or modify} +\item{obj}{(\code{ANY})\cr the object for the accessor to access or modify.} } \value{ -\code{TRUE} if the object has no/empty instantiated column information, -\code{FALSE} otherwise. +\code{TRUE} if the object has no/empty instantiated column information, \code{FALSE} otherwise. } \description{ Does the \code{table}/\code{row}/\code{InstantiatedColumnInfo} object contain no column structure information? diff --git a/man/paginate.Rd b/man/paginate.Rd index 119f50ade..1403d97a9 100644 --- a/man/paginate.Rd +++ b/man/paginate.Rd @@ -36,162 +36,144 @@ paginate_table( ) } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{lpp}{numeric. Maximum lines per page including (re)printed header and context rows} +\item{lpp}{(\code{numeric(1)})\cr maximum lines per page including (re)printed header and context rows.} -\item{min_siblings}{numeric. Minimum sibling rows which must appear on either side of pagination row for a +\item{min_siblings}{(\code{numeric(1)})\cr minimum sibling rows which must appear on either side of pagination row for a mid-subtable split to be valid. Defaults to 2.} -\item{nosplitin}{character. List of names of sub-tables where page-breaks are not allowed, regardless of other +\item{nosplitin}{(\code{character})\cr names of sub-tables where page-breaks are not allowed, regardless of other considerations. Defaults to none.} -\item{colwidths}{numeric vector. Column widths for use with vertical pagination.} +\item{colwidths}{(\code{numeric})\cr a vector of column widths for use in vertical pagination.} -\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 extra debugging messages be shown. Defaults -to \code{FALSE}.} +\item{verbose}{(\code{flag})\cr whether additional information should be displayed to the user. Defaults to \code{FALSE}.} -\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{cpp}{numeric(1) or NULL. Width (in characters) of the pages for -horizontal pagination. \code{NA} (the default) indicates \code{cpp} should be inferred from -the page size; \code{NULL} indicates no horizontal pagination should be done -regardless of page size.} +\item{cpp}{(\code{numeric(1)} or \code{NULL})\cr width (in characters) of the pages for horizontal pagination. +\code{NA} (the default) indicates \code{cpp} should be inferred from the page size; \code{NULL} indicates no horizontal +pagination should be done regardless of page size.} -\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.} } \value{ -for \code{pag_tt_indices} a list of paginated-groups of row-indices of \code{tt}. For \code{paginate_table}, -The subtables defined by subsetting by the indices defined by \code{pag_tt_indices}. +\itemize{ +\item \code{pag_tt_indices} returns a list of paginated-groups of row-indices of \code{tt}. +\item \code{paginate_table} returns the subtables defined by subsetting by the indices defined by \code{pag_tt_indices}. +} } \description{ -Paginate an \code{rtables} table in the vertical and/or horizontal -direction, as required for the specified page size. +Paginate an \code{rtables} table in the vertical and/or horizontal direction, as required for the specified page size. } \details{ -\code{rtables} pagination is context aware, meaning that label rows and -row-group summaries (content rows) are repeated after (vertical) -pagination, as appropriate. This allows the reader to immediately -understand where they are in the table after turning to a new page, -but does also mean that a rendered, paginated table will take up -more lines of text than rendering the table without pagination -would. +\code{rtables} pagination is context aware, meaning that label rows and row-group summaries (content rows) are repeated +after (vertical) pagination, as appropriate. This allows the reader to immediately understand where they are in the +table after turning to a new page, but does also mean that a rendered, paginated table will take up more lines of +text than rendering the table without pagination would. -Pagination also takes into account word-wrapping of title, footer, -column-label, and formatted cell value content. +Pagination also takes into account word-wrapping of title, footer, column-label, and formatted cell value content. -Vertical pagination information (pagination data.frame) is created -using (\code{make_row_df}) +Vertical pagination information (pagination \code{data.frame}) is created using (\code{make_row_df}). -Horizontal pagination is performed by creating a pagination -dataframe for the columns, and then applying the same algorithm -used for vertical pagination to it. +Horizontal pagination is performed by creating a pagination data frame for the columns, and then applying the same +algorithm used for vertical pagination to it. -If physical page size and font information are specified, these are -used to derive lines-per-page (\code{lpp}) and characters-per-page -(\code{cpp}) values. +If physical page size and font information are specified, these are used to derive lines-per-page (\code{lpp}) and +characters-per-page (\code{cpp}) values. The full multi-direction pagination algorithm then is as follows: \enumerate{ -\item Adjust \code{lpp} and \code{cpp} to account for rendered elements that are not rows (columns) +\item Adjust \code{lpp} and \code{cpp} to account for rendered elements that are not rows (columns): } \itemize{ \item titles/footers/column labels, and horizontal dividers in the vertical pagination case \item row-labels, table_inset, and top-left materials in the horizontal case } \enumerate{ -\item Perform 'forced pagination' representing page-by row splits, generating 1 or more tables -\item Perform vertical pagination separately on each table generated in (1) +\item Perform 'forced pagination' representing page-by row splits, generating 1 or more tables. +\item Perform vertical pagination separately on each table generated in (1). \item Perform horizontal pagination \strong{on the entire table} and apply the results to each table -page generated in (1)-(2) -\item Return a list of subtables representing full bi-directional pagination +page generated in (1)-(2). +\item Return a list of subtables representing full bi-directional pagination. } -Pagination in both directions is done using the \emph{Core Pagination Algorithm} -implemented in the \code{formatters} package: +Pagination in both directions is done using the \emph{Core Pagination Algorithm} implemented in the \code{formatters} package: } \section{Pagination Algorithm}{ -Pagination is performed independently in the vertical and horizontal -directions based solely on a \emph{pagination data.frame}, which includes the +Pagination is performed independently in the vertical and horizontal +directions based solely on a \emph{pagination data frame}, which includes the following information for each row/column: \itemize{ -\item number of lines/characters rendering the row will take \strong{after +\item Number of lines/characters rendering the row will take \strong{after word-wrapping} (\code{self_extent}) -\item the indices (\code{reprint_inds}) and number of lines (\code{par_extent}) +\item The indices (\code{reprint_inds}) and number of lines (\code{par_extent}) of the rows which act as \strong{context} for the row -\item the row's number of siblings and position within its siblings +\item The row's number of siblings and position within its siblings } -Given \code{lpp} (\code{cpp}) already adjusted for rendered elements which -are not rows/columns and a dataframe of pagination information, -pagination is performed via the following algorithm, and with a -\code{start = 1}: +Given \code{lpp} (\code{cpp}) is already adjusted for rendered elements which +are not rows/columns and a data frame of pagination information, +pagination is performed via the following algorithm with \code{start = 1}. Core Pagination Algorithm: \enumerate{ -\item Initial guess for pagination point is \code{start + lpp} (\code{start + cpp}) -\item While the guess is not a valid pagination position, and \code{guess > start}, decrement guess and repeat -} +\item Initial guess for pagination position is \code{start + lpp} (\code{start + cpp}) +\item While the guess is not a valid pagination position, and \code{guess > start}, +decrement guess and repeat. \itemize{ -\item an error is thrown if all possible pagination positions between -\code{start} and \code{start + lpp} (\code{start + cpp}) would ever be \verb{< start} +\item An error is thrown if all possible pagination positions between +\code{start} and \code{start + lpp} (\code{start + cpp}) would be \verb{< start} after decrementing } -\enumerate{ \item Retain pagination index -\item if pagination point was less than \code{NROW(tt)} (\code{ncol(tt)}), set +\item If pagination point was less than \code{NROW(tt)} (\code{ncol(tt)}), set \code{start} to \code{pos + 1}, and repeat steps (1) - (4). } -Validating pagination position: +Validating Pagination Position: Given an (already adjusted) \code{lpp} or \code{cpp} value, a pagination is invalid if: \itemize{ -\item The rows/columns on the page would take more than (adjusted) \code{lpp} lines/\code{cpp} -characters to render \strong{including} +\item The rows/columns on the page would take more than (adjusted) \code{lpp} lines/\code{cpp} +characters to render \strong{including}: \itemize{ \item word-wrapping \item (vertical only) context repetition } -\item (vertical only) footnote messages and or section divider lines +\item (vertical only) footnote messages and/or section divider lines take up too many lines after rendering rows \item (vertical only) row is a label or content (row-group summary) row -\item (vertical only) row at the pagination point has siblings, and +\item (vertical only) row at the pagination point has siblings, and it has less than \code{min_siblings} preceding or following siblings \item pagination would occur within a sub-table listed in \code{nosplitin} } @@ -219,7 +201,6 @@ s_summary <- function(x) { } } - lyt <- basic_table() \%>\% split_cols_by(var = "ARM") \%>\% analyze(c("AGE", "SEX", "BEP01FL", "BMRKR1", "BMRKR2", "COUNTRY"), afun = s_summary) diff --git a/man/prune_table.Rd b/man/prune_table.Rd index b04e6ee5e..bf4954dfc 100644 --- a/man/prune_table.Rd +++ b/man/prune_table.Rd @@ -12,18 +12,15 @@ prune_table( ) } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{prune_func}{function. A Function to be called on each subtree which -returns TRUE if the entire subtree should be removed.} +\item{prune_func}{(\code{function})\cr a function to be called on each subtree which returns \code{TRUE} if the +entire subtree should be removed.} -\item{stop_depth}{numeric(1). The depth after which subtrees should not be -checked for pruning. Defaults to \code{NA} which indicates pruning should -happen at all levels} +\item{stop_depth}{(\code{numeric(1)})\cr the depth after which subtrees should not be checked for pruning. +Defaults to \code{NA} which indicates pruning should happen at all levels.} -\item{depth}{numeric(1). Used internally, not intended to be set by the end -user.} +\item{depth}{(\code{numeric(1)})\cr used internally, not intended to be set by the end user.} } \value{ A \code{TableTree} pruned via recursive application of \code{prune_func}. @@ -48,6 +45,6 @@ tbl_to_prune \%>\% prune_table() } \seealso{ -\code{\link[=prune_empty_level]{prune_empty_level()}} for details on this and several other basic -pruning functions included in the \code{rtables} package. +\code{\link[=prune_empty_level]{prune_empty_level()}} for details on this and several other basic pruning functions included +in the \code{rtables} package. } diff --git a/man/qtable_layout.Rd b/man/qtable_layout.Rd index d843740bf..0aee0220a 100644 --- a/man/qtable_layout.Rd +++ b/man/qtable_layout.Rd @@ -3,7 +3,7 @@ \name{qtable_layout} \alias{qtable_layout} \alias{qtable} -\title{Generalized Frequency Table} +\title{Generalized frequency table} \usage{ qtable_layout( data, @@ -41,80 +41,71 @@ qtable( ) } \arguments{ -\item{data}{data.frame. The data to tabulate.} +\item{data}{(\code{data.frame})\cr the data to tabulate.} -\item{row_vars}{character. The names of variables to be used in row facetting.} +\item{row_vars}{(\code{character})\cr the names of variables to be used in row facetting.} -\item{col_vars}{character. The names of variables to be used in column facetting.} +\item{col_vars}{(\code{character})\cr the names of variables to be used in column facetting.} -\item{avar}{character(1). The variable to be analyzed. Defaults to the first variable in \code{data}.} +\item{avar}{(\code{string})\cr the variable to be analyzed. Defaults to the first variable in \code{data}.} -\item{row_labels}{character or NULL. Row label(s) which should be applied to the analysis rows. length must match -the number of rows generated by \code{afun}. See details.} +\item{row_labels}{(\code{character} or \code{NULL})\cr row label(s) which should be applied to the analysis rows. Length must +match the number of rows generated by \code{afun}.} -\item{afun}{function. The function to generate the analysis row cell values. This can be a proper analysis +\item{afun}{(\code{function})\cr the function to generate the analysis row cell values. This can be a proper analysis function, or a function which returns a vector or list. Vectors are taken as multi-valued single cells, whereas lists are interpreted as multiple cells.} -\item{summarize_groups}{logical(1). Should each level of nesting include marginal summary rows. Defaults to \code{FALSE}} +\item{summarize_groups}{(\code{flag})\cr whether each level of nesting should include marginal summary rows. Defaults to +\code{FALSE}.} -\item{title}{character(1). Main title (\code{\link[=main_title]{main_title()}}) is a single string. -Ignored for subtables.} +\item{title}{(\code{string})\cr single string to use as main title (\code{\link[=main_title]{main_title()}}). Ignored for subtables.} -\item{subtitles}{character. Subtitles (\code{\link[=subtitles]{subtitles()}}) can be vector of strings, where -every element is printed in a separate line. Ignored for subtables.} +\item{subtitles}{(\code{character})\cr a vector of strings to use as subtitles (\code{\link[=subtitles]{subtitles()}}), where every element is +printed on a separate line. Ignored for subtables.} -\item{main_footer}{character. Main global (non-referential) footer materials -(\code{\link[=main_footer]{main_footer()}}). If it is a vector of strings, they will be printed on separate -lines.} +\item{main_footer}{(\code{character})\cr a vector of strings to use as main global (non-referential) footer materials +(\code{\link[=main_footer]{main_footer()}}), where every element is printed on a separate line.} -\item{prov_footer}{character. Provenance-related global footer materials -(\code{\link[=prov_footer]{prov_footer()}}). It can be also a vector of strings, printed on different lines. -Generally should not be modified by hand.} +\item{prov_footer}{(\code{character})\cr a vector of strings to use as provenance-related global footer materials +(\code{\link[=prov_footer]{prov_footer()}}), where every element is printed on a separate line.} -\item{show_colcounts}{logical(1). Should column counts be displayed in the -resulting table when this layout is applied to data} +\item{show_colcounts}{(\code{flag})\cr whether column counts should be displayed in the resulting table when this +layout is applied to data.} -\item{drop_levels}{logical(1). Should unobserved factor levels be dropped during facetting. Defaults to \code{TRUE}.} +\item{drop_levels}{(\code{flag})\cr whether unobserved factor levels should be dropped during facetting. Defaults to +\code{TRUE}.} -\item{...}{passed to \code{afun}, if specified. Otherwise ignored.} +\item{...}{additional arguments passed to \code{afun}.} -\item{.default_rlabel}{character(1). This is an implementation detail that should not be set by end users.} +\item{.default_rlabel}{(\code{string})\cr this is an implementation detail that should not be set by end users.} } \value{ -for \code{qtable} a built TableTree object representing the desired table, -for \code{qtable_layout}, a \code{PreDataTableLayouts} object declaring the structure of -the desired table, suitable for passing to \code{build_table}. +\itemize{ +\item \code{qtable} returns a built \code{TableTree} object representing the desired table +\item \code{qtable_layout} returns a \code{PreDataTableLayouts} object declaring the structure of the desired table, suitable for +passing to \code{\link[=build_table]{build_table()}}. +} } \description{ -This function provides a convenience interface for -generating generalizations of a 2-way frequency table. Row and column -space can be facetted by variables, and an analysis function can be specified. - -The function then builds a layout with the specified layout and applies it to -the data provided. +This function provides a convenience interface for generating generalizations of a 2-way frequency table. Row and +column space can be facetted by variables, and an analysis function can be specified. The function then builds a +layout with the specified layout and applies it to the data provided. } \details{ -This function creates a table with a single top-level structure in -both row and column dimensions involving faceting by 0 or more -variables in each. - -The display of the table depends on certain -details of the tabulation. In the case of an \code{afun} which -returns a single cell's contents (either a scalar or a vector -of 2 or 3 elements), the label rows for the deepest-nested row -facets will be hidden and the labels used there will be used as -the analysis row labels. In the case of an \code{afun} which returns a -list (corresponding to multiple cells), the names of the list -will be used as the analysis row labels and the deepest-nested -facet row labels will be visible. - -The table will be annotated in the top-left area with an -informative label displaying the analysis variable (\code{avar}), if -set, and the function used (captured via substitute) where -possible, or 'count' if not. One exception where the user may -directly modify the top-left area (via \code{row_labels}) is the case of -a table with row facets and an \code{afun} which returns a single row. +This function creates a table with a single top-level structure in both row and column dimensions involving faceting +by 0 or more variables in each dimension. + +The display of the table depends on certain details of the tabulation. In the case of an \code{afun} which returns a +single cell's contents (either a scalar or a vector of 2 or 3 elements), the label rows for the deepest-nested row +facets will be hidden and the labels used there will be used as the analysis row labels. In the case of an \code{afun} +which returns a list (corresponding to multiple cells), the names of the list will be used as the analysis row +labels and the deepest-nested facet row labels will be visible. + +The table will be annotated in the top-left area with an informative label displaying the analysis variable +(\code{avar}), if set, and the function used (captured via substitute) where possible, or 'count' if not. One exception +where the user may directly modify the top-left area (via \code{row_labels}) is the case of a table with row facets and +an \code{afun} which returns a single row. } \examples{ qtable(ex_adsl) @@ -132,4 +123,5 @@ suppressWarnings(qtable(ex_adsl, row_vars = "SEX", col_vars = "ARM", avar = "AGE", afun = range )) + } diff --git a/man/rbind.Rd b/man/rbind.Rd index 99793c600..60ae7be46 100644 --- a/man/rbind.Rd +++ b/man/rbind.Rd @@ -2,10 +2,10 @@ % Please edit documentation in R/tt_compatibility.R \name{rbindl_rtables} \alias{rbindl_rtables} -\alias{rbind,VTableNodeInfo-method} \alias{rbind} +\alias{rbind,VTableNodeInfo-method} \alias{rbind2,VTableNodeInfo,ANY-method} -\title{\code{rbind} \code{TableTree} and related objects} +\title{Row-bind \code{TableTree} and related objects} \usage{ rbindl_rtables(x, gap = 0, check_headers = TRUE) @@ -14,23 +14,23 @@ rbindl_rtables(x, gap = 0, check_headers = TRUE) \S4method{rbind2}{VTableNodeInfo,ANY}(x, y) } \arguments{ -\item{x}{\code{VTableNodeInfo}. \code{TableTree}, \code{ElementaryTable} or \code{TableRow} object.} +\item{x}{(\code{VTableNodeInfo})\cr \code{TableTree}, \code{ElementaryTable}, or \code{TableRow} object.} -\item{gap}{deprecated. Ignored.} +\item{gap}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} ignored.} -\item{check_headers}{deprecated. Ignored.} +\item{check_headers}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} ignored.} -\item{\dots}{ANY. Elements to be stacked.} +\item{...}{(\code{ANY})\cr elements to be stacked.} -\item{deparse.level}{numeric(1). Currently Ignored.} +\item{deparse.level}{(\code{numeric(1)})\cr currently ignored.} -\item{y}{\code{VTableNodeInfo}. \code{TableTree}, \code{ElementaryTable} or \code{TableRow} object.} +\item{y}{(\code{VTableNodeInfo})\cr \code{TableTree}, \code{ElementaryTable}, or \code{TableRow} object.} } \value{ A formal table object. } \description{ -\code{rbind} \code{TableTree} and related objects +Row-bind \code{TableTree} and related objects } \note{ When objects are row-bound, titles and footer information is retained from the first object (if any exists) if all @@ -68,4 +68,5 @@ mtbl2 <- with(subset(iris, Species == "setosa"), rtable( rbind(mtbl, mtbl2) rbind(mtbl, rrow(), mtbl2) rbind(mtbl, rrow("aaa"), indent(mtbl2)) + } diff --git a/man/rcell.Rd b/man/rcell.Rd index e1f38e4f3..8df42204d 100644 --- a/man/rcell.Rd +++ b/man/rcell.Rd @@ -29,54 +29,43 @@ non_ref_rcell( ) } \arguments{ -\item{x}{ANY. Cell value.} +\item{x}{(\code{ANY})\cr cell value.} -\item{format}{character(1) or function. The format label (string) or -\code{formatters} function to apply to \code{x}. See -\code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for currently supported -format labels.} +\item{format}{(\code{string} or \code{function})\cr the format label (string) or \code{formatters} function to apply to \code{x}. +See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for currently supported format labels.} -\item{colspan}{integer(1). Column span value.} +\item{colspan}{(\code{integer(1)})\cr column span value.} -\item{label}{character(1). Label or \code{NULL}. If non-null, it will be looked at -when determining row labels.} +\item{label}{(\code{string} or \code{NULL})\cr label. If non-\code{NULL}, it will be looked at when determining row labels.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} -\item{footnotes}{list or \code{NULL}. Referential footnote messages for the cell.} +\item{footnotes}{(\code{list} or \code{NULL})\cr referential footnote messages for the cell.} -\item{align}{character(1) or \code{NULL}. Alignment the value should be rendered with. -It defaults to \code{"center"} if \code{NULL} is used. See \code{\link[formatters:list_formats]{formatters::list_valid_aligns()}} -for currently supported alignments.} +\item{align}{(\code{string} or \code{NULL})\cr alignment the value should be rendered with. Defaults to \code{"center"} if +\code{NULL} is used. See \code{\link[formatters:list_formats]{formatters::list_valid_aligns()}} for all currently supported alignments.} -\item{format_na_str}{character(1). String which should be displayed when -formatted if this cell's value(s) are all NA.} +\item{format_na_str}{(\code{string})\cr string which should be displayed when formatted if this cell's value(s) +are all \code{NA}.} -\item{is_ref}{logical(1). Are we in the reference column (i.e. -.in_ref_col should be passed to this argument)} +\item{is_ref}{(\code{flag})\cr whether function is being used in the reference column (i.e. \code{.in_ref_col} should be +passed to this argument).} -\item{refval}{ANY. Value to use when in the reference column. Defaults -to \code{NULL}} +\item{refval}{(\code{ANY})\cr value to use when in the reference column. Defaults to \code{NULL}.} } \value{ -An object representing the value within a single cell within a -populated table. The underlying structure of this object is an -implementation detail and should not be relied upon beyond calling -accessors for the class. +An object representing the value within a single cell within a populated table. The underlying structure +of this object is an implementation detail and should not be relied upon beyond calling accessors for the class. } \description{ -Construct a cell value and associate formatting, labeling, -indenting, and column spanning information with it. +Construct a cell value and associate formatting, labeling, indenting, and column spanning information with it. } \details{ -\code{non_ref_rcell} provides the common \emph{blank for cells in -the reference column, this value otherwise}, and should be passed the value -of \code{.in_ref_col} when it is used. +\code{non_ref_rcell} provides the common \emph{blank for cells in the reference column, this value otherwise}, and should +be passed the value of \code{.in_ref_col} when it is used. } \note{ -Currently column spanning is only supported for defining header -structure. +Currently column spanning is only supported for defining header structure. } diff --git a/man/reexports.Rd b/man/reexports.Rd index 40a4ad009..e9b22573e 100644 --- a/man/reexports.Rd +++ b/man/reexports.Rd @@ -20,6 +20,7 @@ tf <- tempfile(fileext = ".txt") export_as_txt(tbl, file = tf) system2("cat", tf) } + lyt <- basic_table() \%>\% split_cols_by("ARM") \%>\% analyze(c("AGE", "BMRKR2", "COUNTRY")) @@ -32,6 +33,7 @@ export_as_pdf(tbl, file = tf, pg_height = 4) tf <- tempfile(fileext = ".pdf") export_as_pdf(tbl, file = tf, lpp = 8) } + } \keyword{internal} \description{ diff --git a/man/ref_fnotes.Rd b/man/ref_fnotes.Rd index 852926ebe..a6948bdec 100644 --- a/man/ref_fnotes.Rd +++ b/man/ref_fnotes.Rd @@ -16,7 +16,7 @@ \alias{ref_symbol<-} \alias{ref_msg} \alias{fnotes_at_path<-} -\title{Referential Footnote Accessors} +\title{Referential footnote accessors} \usage{ row_footnotes(obj) @@ -49,21 +49,21 @@ ref_msg(obj) fnotes_at_path(obj, rowpath = NULL, colpath = NULL, reset_idx = TRUE) <- value } \arguments{ -\item{obj}{ANY. The object for the accessor to access or modify} +\item{obj}{(\code{ANY})\cr the object for the accessor to access or modify.} -\item{value}{The new value} +\item{value}{(\code{ANY})\cr the new value.} -\item{rowpath}{character or NULL. Path within row structure. \code{NULL} -indicates the footnote should go on the column rather than cell.} +\item{rowpath}{(\code{character} or \code{NULL})\cr path within row structure. \code{NULL} indicates the footnote should +go on the column rather than cell.} -\item{colpath}{character or NULL. Path within column structure. \code{NULL} -indicates footnote should go on the row rather than cell} +\item{colpath}{(\code{character} or \code{NULL})\cr path within column structure. \code{NULL} indicates footnote should go +on the row rather than cell.} -\item{reset_idx}{logical(1). Should the numbering for referential footnotes -be immediately recalculated. Defaults to TRUE.} +\item{reset_idx}{(\code{flag})\cr whether the numbering for referential footnotes should be immediately +recalculated. Defaults to \code{TRUE}.} } \description{ -Get and set referential footnotes on aspects of a built table +Access and set the referential footnotes aspects of a built table. } \examples{ # How to add referencial footnotes after having created a table @@ -86,6 +86,5 @@ fnotes_at_path(tbl, rowpath = c("SEX", "UNDIFFERENTIATED")) <- "Unfamous paper 2 } \seealso{ -\code{\link[=row_paths]{row_paths()}}, \code{\link[=col_paths]{col_paths()}}, -\code{\link[=row_paths_summary]{row_paths_summary()}}, \code{\link[=col_paths_summary]{col_paths_summary()}} +\code{\link[=row_paths]{row_paths()}}, \code{\link[=col_paths]{col_paths()}}, \code{\link[=row_paths_summary]{row_paths_summary()}}, \code{\link[=col_paths_summary]{col_paths_summary()}} } diff --git a/man/rheader.Rd b/man/rheader.Rd index ffbbf8562..0aaf60536 100644 --- a/man/rheader.Rd +++ b/man/rheader.Rd @@ -7,35 +7,29 @@ rheader(..., format = "xx", .lst = NULL) } \arguments{ -\item{\dots}{row specifications (either as character vectors or the output -from \code{\link{rrow}} or \code{\link{DataRow}}, \code{\link{LabelRow}}, -etc.} +\item{...}{row specifications, either as character vectors or the output from \code{\link[=rrow]{rrow()}}, \code{\link[=DataRow]{DataRow()}}, +\code{\link[=LabelRow]{LabelRow()}}, etc.} -\item{format}{character(1) or function. The format label (string) or -formatter function to apply to the cell values passed via \code{...}. See -\code{\link[formatters]{list_valid_format_labels}} for currently supported -format labels.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr the format label (string) or formatter function to apply to the +cell values passed via \code{...}. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for currently supported format labels.} -\item{.lst}{list. An already-collected list of arguments to be used instead -of the elements of \code{\dots}. Arguments passed via \code{\dots} will be -ignored if this is specified.} +\item{.lst}{(\code{list})\cr an already-collected list of arguments to be used instead of the elements of \code{...}. +Arguments passed via \code{...} will be ignored if this is specified.} } \value{ -a \code{InstantiatedColumnInfo} object. +A \code{InstantiatedColumnInfo} object. } \description{ Create a header } \examples{ h1 <- rheader(c("A", "B", "C")) +h1 h2 <- rheader( rrow(NULL, rcell("group 1", colspan = 2), rcell("group 2", colspan = 2)), rrow(NULL, "A", "B", "A", "B") ) - -h1 - h2 } diff --git a/man/row_accessors.Rd b/man/row_accessors.Rd index ce05b8bd6..479c192d3 100644 --- a/man/row_accessors.Rd +++ b/man/row_accessors.Rd @@ -40,12 +40,12 @@ row_values(obj) <- value \S4method{row_values}{LabelRow}(obj) <- value } \arguments{ -\item{obj}{ANY. The object for the accessor to access or modify} +\item{obj}{(\code{ANY})\cr the object for the accessor to access or modify.} -\item{value}{The new value} +\item{value}{(\code{ANY})\cr the new value.} } \value{ -various, depending on the accessor called. +Various return values depending on the accessor called. } \description{ Row attribute accessors diff --git a/man/row_paths_summary.Rd b/man/row_paths_summary.Rd index f6ba5a740..fc8c54746 100644 --- a/man/row_paths_summary.Rd +++ b/man/row_paths_summary.Rd @@ -3,25 +3,23 @@ \name{row_paths_summary} \alias{row_paths_summary} \alias{col_paths_summary} -\title{Print Row/Col Paths Summary} +\title{Print row/column paths summary} \usage{ row_paths_summary(x) col_paths_summary(x) } \arguments{ -\item{x}{an \code{rtable} object} +\item{x}{(\code{VTableTree})\cr an \code{rtable} object.} } \value{ -A data.frame summarizing the row- or column-structure of \code{x}. +A data frame summarizing the row- or column-structure of \code{x}. } \description{ -Print Row/Col Paths Summary +Print row/column paths summary } \examples{ -library(dplyr) - -ex_adsl_MF <- ex_adsl \%>\% filter(SEX \%in\% c("M", "F")) +ex_adsl_MF <- ex_adsl \%>\% dplyr::filter(SEX \%in\% c("M", "F")) lyt <- basic_table() \%>\% split_cols_by("ARM") \%>\% @@ -48,4 +46,5 @@ tbl2 <- rtable( rrow("r1", 1, 2, 1, 2), rrow("r2", 3, 4, 2, 1) ) col_paths_summary(tbl2) + } diff --git a/man/rowclasses.Rd b/man/rowclasses.Rd index f928b6a09..c9ad05285 100644 --- a/man/rowclasses.Rd +++ b/man/rowclasses.Rd @@ -44,55 +44,47 @@ DataRow(...) ContentRow(...) } \arguments{ -\item{lev}{integer. Nesting level (roughly, indentation level in practical -terms).} +\item{lev}{(\code{integer(1)})\cr nesting level (roughly, indentation level in practical terms).} -\item{label}{character(1). A label (not to be confused with the name) for the -object/structure.} +\item{label}{(\code{string})\cr a label (not to be confused with the name) for the object/structure.} -\item{name}{character(1). Name of the split/table/row being created. Defaults -to same as the corresponding label, but is not required to be.} +\item{name}{(\code{string})\cr name of the split/table/row being created. Defaults to the value of the +corresponding label, but is not required to be.} -\item{vis}{logical. Should the row be visible (\code{LabelRow} only).} +\item{vis}{(\code{flag})\cr whether the row should be visible (\code{LabelRow} only).} -\item{cinfo}{\code{InstantiatedColumnInfo} (or NULL). Column structure for the -object being created.} +\item{cinfo}{(\code{InstantiatedColumnInfo} or \code{NULL})\cr column structure for the object being created.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} -\item{table_inset}{numeric(1). Number of spaces to inset the table header, table -body, referential footnotes, and main_footer, as compared to alignment -of title, subtitle, and provenance footer. Defaults to 0 (no inset).} +\item{table_inset}{(\code{numeric(1)})\cr number of spaces to inset the table header, table body, referential footnotes, +and main footer, as compared to alignment of title, subtitles, and provenance footer. Defaults to 0 (no inset).} -\item{trailing_section_div}{character(1). String which will be used as a section -divider after the printing of the last row contained in this (sub)-table, -unless that row is also the last table row to be printed overall, or -\code{NA_character_} for none (the default). When generated via layouting, this -would correspond to the \code{section_div} of the split under which this table -represents a single facet.} +\item{trailing_section_div}{(\code{string})\cr string which will be used as a section divider after the printing +of the last row contained in this (sub)table, unless that row is also the last table row to be printed overall, +or \code{NA_character_} for none (the default). When generated via layouting, this would correspond to the +\code{section_div} of the split under which this table represents a single facet.} -\item{vals}{list. cell values for the row} +\item{vals}{(\code{list})\cr cell values for the row.} -\item{cspan}{integer. Column span. \code{1} indicates no spanning.} +\item{cspan}{(\code{integer})\cr column span. \code{1} indicates no spanning.} -\item{var}{string, variable name} +\item{var}{(\code{string})\cr variable name.} -\item{format}{\code{FormatSpec}. Format associated with this split. Formats can be -declared via strings (\code{"xx.x"}) or function. In cases such as -\code{analyze} calls, they can character vectors or lists of functions.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr format associated with this split. Formats can be declared via +strings (\code{"xx.x"}) or function. In cases such as \code{analyze} calls, they can be character vectors or lists of +functions. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for a list of all available format strings.} -\item{na_str}{character(1). String that should be displayed when the value of \code{x} is missing. -Defaults to \code{"NA"}.} +\item{na_str}{(\code{string})\cr string that should be displayed when the value of \code{x} is missing. Defaults to \code{"NA"}.} -\item{klass}{Internal detail.} +\item{klass}{(\code{character})\cr internal detail.} -\item{footnotes}{list or NULL. Referential footnotes to be applied at current -level. In post-processing, this can be achieved with \code{\link{fnotes_at_path<-}}.} +\item{footnotes}{(\code{list} or \code{NULL})\cr referential footnotes to be applied at current level. In post-processing, +this can be achieved with \code{\link{fnotes_at_path<-}}.} -\item{\dots}{passed to shared constructor (\code{.tablerow}).} +\item{...}{additional parameters passed to shared constructor (\code{.tablerow}).} } \value{ A formal object representing a table row of the constructed type. @@ -100,7 +92,7 @@ A formal object representing a table row of the constructed type. \description{ Row classes and constructors -Row constructors and Classes +Row constructors and classes } \author{ Gabriel Becker diff --git a/man/rrow.Rd b/man/rrow.Rd index 216489fc7..51266dcf0 100644 --- a/man/rrow.Rd +++ b/man/rrow.Rd @@ -2,31 +2,29 @@ % Please edit documentation in R/tt_compatibility.R \name{rrow} \alias{rrow} -\title{row} +\title{Create an \code{rtable} row} \usage{ rrow(row.name = "", ..., format = NULL, indent = 0, inset = 0L) } \arguments{ -\item{row.name}{if \code{NULL} then an empty string is used as -\code{row.name} of the \code{\link{rrow}}.} +\item{row.name}{(\code{string} or \code{NULL})\cr row name. If \code{NULL}, an empty string is used as \code{row.name} of the +\code{\link[=rrow]{rrow()}}.} -\item{\dots}{cell values} +\item{...}{cell values.} -\item{format}{character(1) or function. The format label (string) or -formatter function to apply to the cell values passed via \code{...}. See -\code{\link[formatters]{list_valid_format_labels}} for currently supported -format labels.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr the format label (string) or formatter function to apply to the +cell values passed via \code{...}. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for currently supported format labels.} -\item{indent}{deprecated.} +\item{indent}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}} -\item{inset}{integer(1). The table inset for the row or table being -constructed. See \code{\link[formatters]{table_inset}}.} +\item{inset}{(\code{integer(1)})\cr the table inset for the row or table being constructed. See +\code{\link[formatters:table_inset]{formatters::table_inset()}} for details.} } \value{ -A row object of the context-appropriate type (label or data) +A row object of the context-appropriate type (label or data). } \description{ -row +Create an \code{rtable} row } \examples{ rrow("ABC", c(1, 2), c(3, 2), format = "xx (xx.\%)") diff --git a/man/rrowl.Rd b/man/rrowl.Rd index 53c0fb26c..9be3d7772 100644 --- a/man/rrowl.Rd +++ b/man/rrowl.Rd @@ -2,31 +2,29 @@ % Please edit documentation in R/tt_compatibility.R \name{rrowl} \alias{rrowl} -\title{\code{rrowl}} +\title{Create an \code{rtable} row from a vector or list of values} \usage{ rrowl(row.name, ..., format = NULL, indent = 0, inset = 0L) } \arguments{ -\item{row.name}{if \code{NULL} then an empty string is used as -\code{row.name} of the \code{\link{rrow}}.} +\item{row.name}{(\code{string} or \code{NULL})\cr row name. If \code{NULL}, an empty string is used as \code{row.name} of the +\code{\link[=rrow]{rrow()}}.} -\item{\dots}{values in vector/list form} +\item{...}{values in vector/list form.} -\item{format}{character(1) or function. The format label (string) or -formatter function to apply to the cell values passed via \code{...}. See -\code{\link[formatters]{list_valid_format_labels}} for currently supported -format labels.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr the format label (string) or formatter function to apply to the +cell values passed via \code{...}. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for currently supported format labels.} -\item{indent}{deprecated.} +\item{indent}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}} -\item{inset}{integer(1). The table inset for the row or table being -constructed. See \code{\link[formatters]{table_inset}}.} +\item{inset}{(\code{integer(1)})\cr the table inset for the row or table being constructed. See +\code{\link[formatters:table_inset]{formatters::table_inset()}} for details.} } \value{ -A row object of the context-appropriate type (label or data) +A row object of the context-appropriate type (label or data). } \description{ -\code{rrowl} +Create an \code{rtable} row from a vector or list of values } \examples{ rrowl("a", c(1, 2, 3), format = "xx") @@ -43,6 +41,7 @@ rrow("ABC", 2, 3) rrowl(row.name = "row 1", c(1, 2), c(3, 4)) rrow(row.name = "row 2", c(1, 2), c(3, 4)) + } \seealso{ Other compatibility: diff --git a/man/rtable.Rd b/man/rtable.Rd index b170fc6f0..d74161289 100644 --- a/man/rtable.Rd +++ b/man/rtable.Rd @@ -3,39 +3,35 @@ \name{rtable} \alias{rtable} \alias{rtablel} -\title{Create a Table} +\title{Create a table} \usage{ rtable(header, ..., format = NULL, hsep = default_hsep(), inset = 0L) rtablel(header, ..., format = NULL, hsep = default_hsep(), inset = 0L) } \arguments{ -\item{header}{Information defining the header (column structure) of the table. -This can be as row objects (legacy), character vectors or a +\item{header}{(\code{TableRow}, \code{character}, or \code{InstantiatedColumnInfo})\cr information defining the header +(column structure) of the table. This can be as row objects (legacy), character vectors, or an \code{InstantiatedColumnInfo} object.} -\item{\dots}{Rows to place in the table.} +\item{...}{rows to place in the table.} -\item{format}{character(1) or function. The format label (string) or -formatter function to apply to the cell values passed via \code{...}. See -\code{\link[formatters]{list_valid_format_labels}} for currently supported -format labels.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr the format label (string) or formatter function to apply to the +cell values passed via \code{...}. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for currently supported format labels.} -\item{hsep}{character(1). Set of character(s) to be repeated as the separator -between the header and body of the table when rendered as text. Defaults to -a connected horizontal line (unicode 2014) in locals that use a UTF -charset, and to \code{-} elsewhere (with a once per session warning). See -\code{\link[formatters:default_horizontal_sep]{formatters::set_default_hsep()}} for further information.} +\item{hsep}{(\code{string})\cr set of characters to be repeated as the separator between the header and body of +the table when rendered as text. Defaults to a connected horizontal line (unicode 2014) in locals that use a UTF +charset, and to \code{-} elsewhere (with a once per session warning). See \code{\link[formatters:default_horizontal_sep]{formatters::set_default_hsep()}} for further +information.} -\item{inset}{integer(1). The table inset for the row or table being -constructed. See \code{\link[formatters]{table_inset}}.} +\item{inset}{(\code{integer(1)})\cr the table inset for the row or table being constructed. See +\code{\link[formatters:table_inset]{formatters::table_inset()}} for details.} } \value{ -a formal table object of the appropriate type (\code{ElementaryTable} -or \code{TableTree}) +A formal table object of the appropriate type (\code{ElementaryTable} or \code{TableTree}). } \description{ -Create a Table +Create a table } \examples{ rtable( @@ -44,8 +40,8 @@ rtable( rrow("more stuff", rcell(pi, format = "xx.xx"), "test", "and more") ) - # Table with multirow header + sel <- iris$Species == "setosa" mtbl <- rtable( header = rheader( @@ -89,8 +85,8 @@ tbl row.names(tbl) names(tbl) - # Subsetting + tbl[1, ] tbl[, 1] @@ -101,13 +97,13 @@ tbl[3, 2] tbl[5, 1] tbl[5, 2] -# # Data Structure methods +# Data Structure methods + dim(tbl) nrow(tbl) ncol(tbl) names(tbl) - # Colspans tbl2 <- rtable( @@ -116,7 +112,6 @@ tbl2 <- rtable( rrow("r1", 1, 2, 3, 4, 5), rrow("r2", rcell("sp2", colspan = 2), "sp1", rcell("sp2-2", colspan = 2)) ) - tbl2 } diff --git a/man/rtables-package.Rd b/man/rtables-package.Rd new file mode 100644 index 000000000..779a8cb5a --- /dev/null +++ b/man/rtables-package.Rd @@ -0,0 +1,42 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/package.R +\docType{package} +\name{rtables-package} +\alias{rtables} +\alias{rtables-package} +\title{rtables: Reporting Tables} +\description{ +\if{html}{\figure{logo.png}{options: style='float: right' alt='logo' width='120'}} + +Reporting tables often have structure that goes beyond simple rectangular data. The 'rtables' package provides a framework for declaring complex multi-level tabulations and then applying them to data. This framework models both tabulation and the resulting tables as hierarchical, tree-like objects which support sibling sub-tables, arbitrary splitting or grouping of data in row and column dimensions, cells containing multiple values, and the concept of contextual summary computations. A convenient pipe-able interface is provided for declaring table layouts and the corresponding computations, and then applying them to data. +} +\seealso{ +Useful links: +\itemize{ + \item \url{https://github.com/insightsengineering/rtables} + \item \url{https://insightsengineering.github.io/rtables/} + \item Report bugs at \url{https://github.com/insightsengineering/rtables/issues} +} + +} +\author{ +\strong{Maintainer}: Joe Zhu \email{joe.zhu@roche.com} [contributor] + +Authors: +\itemize{ + \item Gabriel Becker \email{gabembecker@gmail.com} (Original creator of the package) + \item Adrian Waddell \email{adrian.waddell@gene.com} +} + +Other contributors: +\itemize{ + \item Daniel Sabanés Bové \email{daniel.sabanes_bove@roche.com} [contributor] + \item Maximilian Mordig \email{maximilian_oliver.mordig@roche.com} [contributor] + \item Davide Garolini \email{davide.garolini@roche.com} [contributor] + \item Emily de la Rua \email{emily.de_la_rua@contractors.roche.com} [contributor] + \item Abinaya Yogasekaram \email{abinaya.yogasekaram@contractors.roche.com} [contributor] + \item F. Hoffmann-La Roche AG [copyright holder, funder] +} + +} +\keyword{internal} diff --git a/man/rtinner.Rd b/man/rtinner.Rd index f94751a68..c8df65209 100644 --- a/man/rtinner.Rd +++ b/man/rtinner.Rd @@ -19,33 +19,32 @@ simple_analysis(x, ...) \S4method{simple_analysis}{ANY}(x, ...) } \arguments{ -\item{x}{the \emph{already split} data being tabulated for a particular cell/set of cells} +\item{x}{(\code{vector})\cr the \emph{already split} data being tabulated for a particular cell/set of cells.} -\item{\dots}{passed on directly} +\item{...}{additional parameters to pass on.} } \value{ -an \code{RowsVerticalSection} object (or \code{NULL}). The details of -this object should be considered an internal implementation detail. +A \code{RowsVerticalSection} object (or \code{NULL}). The details of this object should be considered an +internal implementation detail. } \description{ -This function is used when \code{\link{analyze}} is invoked +This function is used when \code{\link[=analyze]{analyze()}} is invoked. } \details{ This function has the following behavior given particular types of inputs: \describe{ -\item{numeric}{calls \code{\link{mean}} on \code{x}} -\item{logical}{calls \code{\link{sum}} on \code{x}} -\item{factor}{calls \code{\link{length}} on \code{x}} +\item{numeric}{calls \code{\link[=mean]{mean()}} on \code{x}.} +\item{logical}{calls \code{\link[=sum]{sum()}} on \code{x}.} +\item{factor}{calls \code{\link[=length]{length()}} on \code{x}.} } -\code{in_rows} is called on the resulting value(s). - -All other classes of input currently lead to an error. +The \code{\link[=in_rows]{in_rows()}} function is called on the resulting value(s). All other classes of input currently lead to an error. } \examples{ simple_analysis(1:3) simple_analysis(iris$Species) simple_analysis(iris$Species == "setosa") + } \author{ Gabriel Becker and Adrian Waddell diff --git a/man/sanitize_table_struct.Rd b/man/sanitize_table_struct.Rd index 5ced871b1..1792b5387 100644 --- a/man/sanitize_table_struct.Rd +++ b/man/sanitize_table_struct.Rd @@ -2,30 +2,28 @@ % Please edit documentation in R/validate_table_struct.R \name{sanitize_table_struct} \alias{sanitize_table_struct} -\title{Sanitize degenerate table structures (Experimental)} +\title{Sanitize degenerate table structures} \usage{ sanitize_table_struct(tt, empty_msg = "-- This Section Contains No Data --") } \arguments{ -\item{tt}{\code{TableTree}} +\item{tt}{(\code{TableTree})\cr a \code{TableTree} object.} -\item{empty_msg}{character(1). The string which should be spanned across -the inserted empty rows.} +\item{empty_msg}{(\code{string})\cr the string which should be spanned across the inserted empty rows.} } \value{ -If \code{tt} is already valid, it is returned unmodified. If \code{tt} is -degenerate, a modified, non-degenerate version of the table is returned. +If \code{tt} is already valid, it is returned unmodified. If \code{tt} is degenerate, a modified, non-degenerate +version of the table is returned. } \description{ -Experimental function to correct structure -of degenerate tables by adding messaging rows to empty -sub-structures. +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} + +Experimental function to correct structure of degenerate tables by adding messaging rows to empty sub-structures. } \details{ -This function locates degenerate portions of the table (including the table -overall in the case of a table with no data rows) and inserts a row -which spans all columns with the message \code{empty_msg} at each one, -generating a table guaranteed to be non-degenerate. +This function locates degenerate portions of the table (including the table overall in the case of a table with no +data rows) and inserts a row which spans all columns with the message \code{empty_msg} at each one, generating a table +guaranteed to be non-degenerate. } \examples{ sanitize_table_struct(rtable("cool beans")) @@ -38,4 +36,11 @@ lyt <- basic_table() \%>\% ## Degenerate because it doesn't have any analyze calls -> no data rows badtab <- build_table(lyt, DM) sanitize_table_struct(badtab) + +} +\seealso{ +Other table structure validation functions: +\code{\link{find_degen_struct}()}, +\code{\link{validate_table_struct}()} } +\concept{table structure validation functions} diff --git a/man/score_funs.Rd b/man/score_funs.Rd index 6958a285d..534328cd9 100644 --- a/man/score_funs.Rd +++ b/man/score_funs.Rd @@ -10,20 +10,17 @@ cont_n_allcols(tt) cont_n_onecol(j) } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{j}{numeric(1). Number of column used for scoring.} +\item{j}{(\code{numeric(1)})\cr index of column used for scoring.} } \value{ -A single numeric value indicating score according to the relevant -metric for \code{tt}, to be used when sorting. +A single numeric value indicating score according to the relevant metric for \code{tt}, to be used when sorting. } \description{ Score functions for sorting \code{TableTrees} } \seealso{ -For examples and details please read main documentation -\code{\link[=sort_at_path]{sort_at_path()}} and relevant vignette -((\href{https://insightsengineering.github.io/rtables/main/articles/sorting_pruning.html}{Sorting and Pruning})) +For examples and details, please read the documentation for \code{\link[=sort_at_path]{sort_at_path()}} and the +\href{https://insightsengineering.github.io/rtables/main/articles/sorting_pruning.html}{Sorting and Pruning} vignette. } diff --git a/man/section_div.Rd b/man/section_div.Rd index 1d10c7102..c6baa06f6 100644 --- a/man/section_div.Rd +++ b/man/section_div.Rd @@ -21,7 +21,7 @@ \alias{top_level_section_div,PreDataTableLayouts-method} \alias{top_level_section_div<-} \alias{top_level_section_div<-,PreDataTableLayouts-method} -\title{Section dividers getter and setter} +\title{Section dividers accessor and setter} \usage{ section_div(obj) @@ -62,15 +62,15 @@ top_level_section_div(obj) <- value \S4method{top_level_section_div}{PreDataTableLayouts}(obj) <- value } \arguments{ -\item{obj}{Table object. This can be of any class that inherits from \code{VTableTree} +\item{obj}{(\code{VTableTree})\cr table object. This can be of any class that inherits from \code{VTableTree} or \code{TableRow}/\code{LabelRow}.} -\item{only_sep_sections}{logical(1). Defaults to \code{FALSE} for \verb{section_div<-}. Allows +\item{only_sep_sections}{(\code{flag})\cr defaults to \code{FALSE} for \verb{section_div<-}. Allows you to set the section divider only for sections that are splits or analyses if the number of values is less than the number of rows in the table. If \code{TRUE}, the section divider will be set for all rows of the table.} -\item{value}{character. Vector of single characters to use as section dividers. Each character +\item{value}{(\code{character})\cr vector of single characters to use as section dividers. Each character is repeated such that all section dividers span the width of the table. Each character that is not \code{NA_character_} will produce a trailing separator for each row of the table. \code{value} length should reflect the number of rows, or be between 1 and the number of splits/levels. diff --git a/man/sf_args.Rd b/man/sf_args.Rd index 772d228e0..b49c12269 100644 --- a/man/sf_args.Rd +++ b/man/sf_args.Rd @@ -2,25 +2,23 @@ % Please edit documentation in R/argument_conventions.R \name{sf_args} \alias{sf_args} -\title{Split Function Arg Conventions} +\title{Split function argument conventions} \usage{ sf_args(trim, label, first) } \arguments{ -\item{trim}{logical(1). Should splits corresponding with 0 observations be -kept when tabulating.} +\item{trim}{(\code{flag})\cr whether splits corresponding with 0 observations should be kept when tabulating.} -\item{label}{character(1). A label (not to be confused with the name) for the -object/structure.} +\item{label}{(\code{string})\cr a label (not to be confused with the name) for the object/structure.} -\item{first}{logical(1). Should the created split level be placed first in -the levels (\code{TRUE}) or last (\code{FALSE}, the default).} +\item{first}{(\code{flag})\cr whether the created split level should be placed first in the levels (\code{TRUE}) or +last (\code{FALSE}, the default).} } \value{ -NULL (this is an argument template dummy function) +No return value. } \description{ -Split Function Arg Conventions +Split function argument conventions } \seealso{ Other conventions: diff --git a/man/sort_at_path.Rd b/man/sort_at_path.Rd index 519cf238d..7d2c44aad 100644 --- a/man/sort_at_path.Rd +++ b/man/sort_at_path.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/tt_sort.R \name{sort_at_path} \alias{sort_at_path} -\title{Sorting a Table at a Specific Path} +\title{Sorting a table at a specific path} \usage{ sort_at_path( tt, @@ -14,91 +14,70 @@ sort_at_path( ) } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{path}{character. A vector path for a position within the structure of a -\code{tabletree}. Each element represents a subsequent choice amongst the children -of the previous choice.} +\item{path}{(\code{character})\cr a vector path for a position within the structure of a \code{TableTree}. Each element +represents a subsequent choice amongst the children of the previous choice.} -\item{scorefun}{function. Scoring function, should accept the type of -children directly under the position at \code{path} (either \code{VTableTree}, -\code{VTableRow}, or \code{VTableNodeInfo}, which covers both) and return a numeric value +\item{scorefun}{(\code{function})\cr scoring function. Should accept the type of children directly under the position +at \code{path} (either \code{VTableTree}, \code{VTableRow}, or \code{VTableNodeInfo}, which covers both) and return a numeric value to be sorted.} -\item{decreasing}{logical(1). Should the the scores generated by -\code{scorefun} be sorted in decreasing order. If unset (the default of -\code{NA}), it is set to \code{TRUE} if the generated scores are numeric -and \code{FALSE} if they are characters.} +\item{decreasing}{(\code{flag})\cr whether the scores generated by \code{scorefun} should be sorted in decreasing order. If +unset (the default of \code{NA}), it is set to \code{TRUE} if the generated scores are numeric and \code{FALSE} if they are +characters.} -\item{na.pos}{character(1). What should be done with children (sub-trees/rows) -with \code{NA} scores. Defaults to \code{"omit"}, which removes them, other -allowed values are \code{"last"} and \code{"first"} which indicate where -they should be placed in the order.} +\item{na.pos}{(\code{string})\cr what should be done with children (sub-trees/rows) with \code{NA} scores. Defaults to +\code{"omit"}, which removes them. Other allowed values are \code{"last"} and \code{"first"}, which indicate where \code{NA} scores +should be placed in the order.} -\item{.prev_path}{character. Internal detail, do not set manually.} +\item{.prev_path}{(\code{character})\cr internal detail, do not set manually.} } \value{ -A \code{TableTree} with the same structure as \code{tt} with the exception -that the requested sorting has been done at \code{path}. +A \code{TableTree} with the same structure as \code{tt} with the exception that the requested sorting has been done +at \code{path}. } \description{ -Main sorting function to order the substructure of a \code{TableTree} -at a particular Path in the table tree. +Main sorting function to order the sub-structure of a \code{TableTree} at a particular path in the table tree. } \details{ -\code{sort_at_path}, given a path, locates the (sub)table(s) described -by the path (see below for handling of the \code{"*"} wildcard). For -each such subtable, it then calls \code{scorefun} on each direct -child of the table, using the resulting scores to determine -their sorted order. \code{tt} is then modified to reflect each of -these one or more sorting operations. - -In \code{path}, a leading \code{"root"} element will be ignored, regardless -of whether this matches the object name (and thus actual root -path name) of \code{tt}. Including \code{"root"} in paths where it does not -match the name of \code{tt} may mask deeper misunderstandings of how -valid paths within a \code{TableTree} object correspond to the layout -used to originally declare it, which we encourage users to -avoid. - -\code{path} can include the "wildcard" \code{"*"} as a step, -which translates roughly to \emph{any} node/branching element and means -that each child at that step will be \emph{separately} sorted based on -\code{scorefun} and the remaining \code{path} entries. This can occur -multiple times in a path. - -A list of valid (non-wildcard) paths can be seen in the \code{path} column -of the data.frame created by \code{\link[=make_row_df]{make_row_df()}} with the \code{visible_only} -argument set to \code{FALSE}. It can also be inferred from the summary -given by \code{\link[=table_structure]{table_structure()}}. - -Note that sorting needs a deeper understanding of table structure in -\code{rtables}. Please consider reading related vignette -(\href{https://insightsengineering.github.io/rtables/main/articles/sorting_pruning.html}{Sorting and Pruning}) -and explore table structure with useful functions like \code{\link[=table_structure]{table_structure()}} -and \code{\link[=row_paths_summary]{row_paths_summary()}}. It is also very important to understand the -difference between "content" rows and "data" rows. The first one analyzes -and describes the split variable generally and is generated with -\code{\link[=summarize_row_groups]{summarize_row_groups()}}, while the second one is commonly produced by -calling one of the various \code{\link[=analyze]{analyze()}} instances. - -Built-in score functions are \code{\link[=cont_n_allcols]{cont_n_allcols()}} and \code{\link[=cont_n_onecol]{cont_n_onecol()}}. -They are both working with content rows (coming from \code{\link[=summarize_row_groups]{summarize_row_groups()}}) -while a custom score function needs to be used on \code{DataRow}s. Here, some +\code{sort_at_path}, given a path, locates the (sub)table(s) described by the path (see below for handling of the \code{"*"} +wildcard). For each such subtable, it then calls \code{scorefun} on each direct child of the table, using the resulting +scores to determine their sorted order. \code{tt} is then modified to reflect each of these one or more sorting +operations. + +In \code{path}, a leading \code{"root"} element will be ignored, regardless of whether this matches the object name (and thus +actual root path name) of \code{tt}. Including \code{"root"} in paths where it does not match the name of \code{tt} may mask deeper +misunderstandings of how valid paths within a \code{TableTree} object correspond to the layout used to originally declare +it, which we encourage users to avoid. + +\code{path} can include the "wildcard" \code{"*"} as a step, which translates roughly to \emph{any} node/branching element and means +that each child at that step will be \emph{separately} sorted based on \code{scorefun} and the remaining \code{path} entries. This +can occur multiple times in a path. + +A list of valid (non-wildcard) paths can be seen in the \code{path} column of the \code{data.frame} created by \code{\link[=make_row_df]{make_row_df()}} +with the \code{visible_only} argument set to \code{FALSE}. It can also be inferred from the summary given by +\code{\link[=table_structure]{table_structure()}}. + +Note that sorting needs a deeper understanding of table structure in \code{rtables}. Please consider reading the related +vignette (\href{https://insightsengineering.github.io/rtables/main/articles/sorting_pruning.html}{Sorting and Pruning}) +and explore table structure with useful functions like \code{\link[=table_structure]{table_structure()}} and \code{\link[=row_paths_summary]{row_paths_summary()}}. It is also +very important to understand the difference between "content" rows and "data" rows. The first one analyzes and +describes the split variable generally and is generated with \code{\link[=summarize_row_groups]{summarize_row_groups()}}, while the second one is +commonly produced by calling one of the various \code{\link[=analyze]{analyze()}} instances. + +Built-in score functions are \code{\link[=cont_n_allcols]{cont_n_allcols()}} and \code{\link[=cont_n_onecol]{cont_n_onecol()}}. They are both working with content rows +(coming from \code{\link[=summarize_row_groups]{summarize_row_groups()}}) while a custom score function needs to be used on \code{DataRow}s. Here, some useful descriptor and accessor functions (coming from related vignette): \itemize{ -\item \code{\link[=cell_values]{cell_values()}} - Retrieves a named list of a \code{TableRow} or -\code{TableTree} object's values. -\item \code{\link[=obj_name]{obj_name()}} - Retrieves the name of an object. Note this can differ -from the label that is displayed (if any is) when printing. -\item \code{\link[=obj_label]{obj_label()}} - Retrieves the display label of an object. Note this -can differ from the name that appears in the path. -\item \code{\link[=content_table]{content_table()}} - Retrieves a \code{TableTree} object's content table -(which contains its summary rows). -\item \code{\link[=tree_children]{tree_children()}} - Retrieves a \code{TableTree} object's direct children -(either subtables, rows or possibly a mix thereof, though that -should not happen in practice). +\item \code{\link[=cell_values]{cell_values()}} - Retrieves a named list of a \code{TableRow} or \code{TableTree} object's values. +\item \code{\link[=obj_name]{obj_name()}} - Retrieves the name of an object. Note this can differ from the label that is displayed (if any is) +when printing. +\item \code{\link[=obj_label]{obj_label()}} - Retrieves the display label of an object. Note this can differ from the name that appears in the +path. +\item \code{\link[=content_table]{content_table()}} - Retrieves a \code{TableTree} object's content table (which contains its summary rows). +\item \code{\link[=tree_children]{tree_children()}} - Retrieves a \code{TableTree} object's direct children (either subtables, rows or possibly a mix +thereof, though that should not happen in practice). } } \examples{ @@ -147,7 +126,9 @@ sort_at_path(tbl, c("RACE", "*", "STRATA1", "*", "AGE"), scorefun) } \seealso{ -score functions \code{\link[=cont_n_allcols]{cont_n_allcols()}} and \code{\link[=cont_n_onecol]{cont_n_onecol()}}; -\code{\link[=make_row_df]{make_row_df()}} and \code{\link[=table_structure]{table_structure()}} for pathing information; -\code{\link[=tt_at_path]{tt_at_path()}} to select a table's (sub)structure at a given path. +\itemize{ +\item Score functions \code{\link[=cont_n_allcols]{cont_n_allcols()}} and \code{\link[=cont_n_onecol]{cont_n_onecol()}}. +\item \code{\link[=make_row_df]{make_row_df()}} and \code{\link[=table_structure]{table_structure()}} for pathing information. +\item \code{\link[=tt_at_path]{tt_at_path()}} to select a table's (sub)structure at a given path. +} } diff --git a/man/spl_context.Rd b/man/spl_context.Rd index 0ef38d365..ffd955e61 100644 --- a/man/spl_context.Rd +++ b/man/spl_context.Rd @@ -4,52 +4,40 @@ \alias{spl_context} \title{.spl_context within analysis and split functions} \description{ -\code{.spl_context} is an optional parameter for any of \code{rtables}' special -functions, them being \code{afun} (analysis function in \link{analyze}), -\code{cfun} (content or label function in \link{summarize_row_groups}), -or \code{split_fun} (e.g. for \link{split_rows_by}). +\code{.spl_context} is an optional parameter for any of rtables' special functions, i.e. \code{afun} (analysis function +in \code{\link[=analyze]{analyze()}}), \code{cfun} (content or label function in \code{\link[=summarize_row_groups]{summarize_row_groups()}}), or \code{split_fun} (e.g. for +\code{\link[=split_rows_by]{split_rows_by()}}). } \details{ -The \code{.spl_context} \code{data.frame} gives information about the subsets of data -corresponding to the splits within-which the current \code{analyze} action is -nested. Taken together, these correspond to the path that the resulting (set -of) rows the analysis function is creating, although the information is in a -slightly different form. Each split (which correspond to groups of rows in -the resulting table), as well as the initial 'root' "split", is represented +The \code{.spl_context} \code{data.frame} gives information about the subsets of data corresponding to the splits within +which the current \code{analyze} action is nested. Taken together, these correspond to the path that the resulting (set +of) rows the analysis function is creating, although the information is in a slightly different form. Each split +(which correspond to groups of rows in the resulting table), as well as the initial 'root' "split", is represented via the following columns: + \describe{ -\item{split}{The name of the split (often the variable being split in the -simple case)} -\item{value}{The string representation of the value at that split} -\item{full_parent_df}{a dataframe containing the full data (i.e. across all -columns) corresponding to the path defined by the combination of \code{split} -and \code{value} of this row \emph{and all rows above this row}} -\item{all_cols_n}{the number of observations corresponding to this row -grouping (union of all columns)} -\item{\emph{(row-split and analyze contexts only)} <1 column for each -column in the table structure}{ These list columns (named the same as -\code{names(col_exprs(tab))}) contain logical vectors corresponding to -the subset of this row's \code{full_parent_df} corresponding to that column} -\item{cur_col_id}{Identifier of the current column. This may be an internal -name, constructed by pasting the column path together} -\item{cur_col_subset}{List column containing logical vectors indicating the -subset of that row's \code{full_parent_df} for the column currently being -created by the analysis function} -\item{cur_col_expr}{List of current column expression. This may be used to -filter \code{.alt_df_row} or any external data by column. Filtering \code{.alt_df_row} -by columns produces \code{.alt_df}.} -\item{cur_col_n}{integer column containing the observation counts for that -split} -\item{cur_col_split}{Current column split names. This is recovered from the -current column path} -\item{cur_col_split_val}{Current column split values. This is recovered from the -current column path} +\item{split}{The name of the split (often the variable being split).} +\item{value}{The string representation of the value at that split (\code{split}).} +\item{full_parent_df}{A \code{data.frame} containing the full data (i.e. across all columns) corresponding to the path +defined by the combination of \code{split} and \code{value} of this row \emph{and all rows above this row}.} +\item{all_cols_n}{The number of observations corresponding to the row grouping (union of all columns).} +\item{column for each column in the table structure (\emph{row-split and analyze contexts only})}{These list columns +(named the same as \code{names(col_exprs(tab))}) contain logical vectors corresponding to the subset of this row's +\code{full_parent_df} corresponding to the column.} +\item{cur_col_id}{Identifier of the current column. This may be an internal name, constructed by pasting the +column path together.} +\item{cur_col_subset}{List column containing logical vectors indicating the subset of this row's \code{full_parent_df} +for the column currently being created by the analysis function.} +\item{cur_col_expr}{List of current column expression. This may be used to filter \code{.alt_df_row}, or any external +data, by column. Filtering \code{.alt_df_row} by columns produces \code{.alt_df}.} +\item{cur_col_n}{Integer column containing the observation counts for that split.} +\item{cur_col_split}{Current column split names. This is recovered from the current column path.} +\item{cur_col_split_val}{Current column split values. This is recovered from the current column path.} } - -\emph{note Within analysis functions that accept \code{.spl_context}, the -\code{all_cols_n} and \code{cur_col_n} columns of the dataframe will contain the 'true' -observation counts corresponding to the row-group and row-group x column -subsets of the data. These numbers will not, and currently cannot, reflect -alternate column observation counts provided by the \code{alt_counts_df}, -\code{col_counts} or \code{col_total} arguments to \code{\link{build_table}}} +} +\note{ +Within analysis functions that accept \code{.spl_context}, the \code{all_cols_n} and \code{cur_col_n} columns of the data frame +will contain the 'true' observation counts corresponding to the row-group and row-group x column subsets of the +data. These numbers will not, and currently cannot, reflect alternate column observation counts provided by the +\code{alt_counts_df}, \code{col_counts} or \code{col_total} arguments to \code{\link[=build_table]{build_table()}}. } diff --git a/man/spl_context_to_disp_path.Rd b/man/spl_context_to_disp_path.Rd index 84530ec5b..59d9f7422 100644 --- a/man/spl_context_to_disp_path.Rd +++ b/man/spl_context_to_disp_path.Rd @@ -2,17 +2,16 @@ % Please edit documentation in R/utils.R \name{spl_context_to_disp_path} \alias{spl_context_to_disp_path} -\title{Translate spl_context to Path for display in error messages} +\title{Translate spl_context to a path to display in error messages} \usage{ spl_context_to_disp_path(ctx) } \arguments{ -\item{ctx}{data.frame. The \code{spl_context} data.frame where the error occurred} +\item{ctx}{(\code{data.frame})\cr the \code{spl_context} data frame where the error occurred.} } \value{ -A character string containing a description of the row path corresponding -to the \code{ctx} +A character string containing a description of the row path corresponding to \code{ctx}. } \description{ -Translate spl_context to Path for display in error messages +Translate spl_context to a path to display in error messages } diff --git a/man/spl_variable.Rd b/man/spl_variable.Rd index dbb9ff670..70d9eae61 100644 --- a/man/spl_variable.Rd +++ b/man/spl_variable.Rd @@ -6,7 +6,7 @@ \alias{spl_variable,VarDynCutSplit-method} \alias{spl_variable,VarStaticCutSplit-method} \alias{spl_variable,Split-method} -\title{Variable Associated With a Split} +\title{Variable associated with a split} \usage{ spl_variable(spl) @@ -19,20 +19,16 @@ spl_variable(spl) \S4method{spl_variable}{Split}(spl) } \arguments{ -\item{spl}{Split. The split object} +\item{spl}{(\code{VarLevelSplit})\cr the split object.} } \value{ -for splits with a single variable associated with them, the split, for others, an error is raised. +For splits with a single variable associated with them, returns the split. Otherwise, an error is raised. } \description{ -This function is intended for use when writing custom splitting -logic. In cases where the split is associated with a single -variable, the name of that variable will be returned. At time of -writing this includes splits generated via the -\code{\link{split_rows_by}}, \code{\link{split_cols_by}}, -\code{\link{split_rows_by_cuts}}, \code{\link{split_cols_by_cuts}}, -\code{\link{split_rows_by_cutfun}}, and -\code{\link{split_cols_by_cutfun}} layout directives. +This function is intended for use when writing custom splitting logic. In cases where the split is associated with +a single variable, the name of that variable will be returned. At time of writing this includes splits generated +via the \code{\link[=split_rows_by]{split_rows_by()}}, \code{\link[=split_cols_by]{split_cols_by()}}, \code{\link[=split_rows_by_cuts]{split_rows_by_cuts()}}, \code{\link[=split_cols_by_cuts]{split_cols_by_cuts()}}, +\code{\link[=split_rows_by_cutfun]{split_rows_by_cutfun()}}, and \code{\link[=split_cols_by_cutfun]{split_cols_by_cutfun()}} layout directives. } \seealso{ \code{\link{make_split_fun}} diff --git a/man/split_cols_by.Rd b/man/split_cols_by.Rd index f6c36c0bd..6c59c0c7c 100644 --- a/man/split_cols_by.Rd +++ b/man/split_cols_by.Rd @@ -18,92 +18,73 @@ split_cols_by( ) } \arguments{ -\item{lyt}{layout object pre-data used for tabulation} +\item{lyt}{(\code{PreDataTableLayouts})\cr layout object pre-data used for tabulation.} -\item{var}{string, variable name} +\item{var}{(\code{string})\cr variable name.} -\item{labels_var}{string, name of variable containing labels to be displayed -for the values of \code{var}} +\item{labels_var}{(\code{string})\cr name of variable containing labels to be displayed for the values of \code{var}.} -\item{split_label}{string. Label string to be associated with the table -generated by the split. Not to be confused with labels assigned to each -child (which are based on the data and type of split during tabulation).} +\item{split_label}{(\code{string})\cr label to be associated with the table generated by the split. Not to be confused +with labels assigned to each child (which are based on the data and type of split during tabulation).} -\item{split_fun}{function/NULL. custom splitting function See -\code{\link{custom_split_funs}}} +\item{split_fun}{(\code{function} or \code{NULL})\cr custom splitting function. See \link{custom_split_funs}.} -\item{format}{\code{FormatSpec}. Format associated with this split. Formats can be -declared via strings (\code{"xx.x"}) or function. In cases such as -\code{analyze} calls, they can character vectors or lists of functions.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr format associated with this split. Formats can be declared via +strings (\code{"xx.x"}) or function. In cases such as \code{analyze} calls, they can be character vectors or lists of +functions. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for a list of all available format strings.} -\item{nested}{boolean. Should this layout instruction be applied within the -existing layout structure \emph{if possible} (\code{TRUE}, the default) or as a -new top-level element (`FALSE). Ignored if it would nest a split underneath -analyses, which is not allowed.} +\item{nested}{(\code{logical})\cr whether this layout instruction should be applied within the existing layout structure +\emph{if possible} (\code{TRUE}, the default) or as a new top-level element (\code{FALSE}). Ignored if it would nest a split +underneath analyses, which is not allowed.} -\item{child_labels}{string. One of \code{"default"}, \code{"visible"}, -\code{"hidden"}. What should the display behavior be for the labels (i.e. -label rows) of the children of this split. Defaults to \code{"default"} -which flags the label row as visible only if the child has 0 content rows.} +\item{child_labels}{(\code{string})\cr the display behavior for the labels (i.e. label rows) of the children of this +split. Accepts \code{"default"}, \code{"visible"}, and \code{"hidden"}. Defaults to \code{"default"} which flags the label row as +visible only if the child has 0 content rows.} -\item{extra_args}{list. Extra arguments to be passed to the tabulation -function. Element position in the list corresponds to the children of this -split. Named elements in the child-specific lists are ignored if they do +\item{extra_args}{(\code{list})\cr extra arguments to be passed to the tabulation function. Element position in the list +corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do not match a formal argument of the tabulation function.} -\item{ref_group}{character(1) or \code{NULL}. Level of \code{var} which should be -considered ref_group/reference} +\item{ref_group}{(\code{string} or \code{NULL})\cr level of \code{var} that should be considered \code{ref_group}/reference.} } \value{ -A \code{PreDataTableLayouts} object suitable for passing to further -layouting functions, and to \code{build_table}. +A \code{PreDataTableLayouts} object suitable for passing to further layouting functions, and to \code{\link[=build_table]{build_table()}}. } \description{ -Will generate children for each subset of a categorical variable +Will generate children for each subset of a categorical variable. } \section{Custom Splitting Function Details}{ -User-defined custom split functions can perform any type of computation on -the incoming data provided that they meet the contract for generating -'splits' of the incoming data 'based on' the split object. +User-defined custom split functions can perform any type of computation on the incoming data provided that they +meet the requirements for generating "splits" of the incoming data based on the split object. Split functions are functions that accept: \describe{ -\item{df}{data.frame of incoming data to be split} -\item{spl}{a Split object. this is largely an internal detail custom -functions will not need to worry about, but \code{obj_name(spl)}, for -example, will give the name of the split as it will appear in paths in the -resulting table} -\item{vals}{Any pre-calculated values. If given non-null values, the values -returned should match these. Should be NULL in most cases and can likely be -ignored} -\item{labels}{Any pre-calculated value labels. Same as above for -\code{values}} -\item{trim}{If \code{TRUE}, resulting splits that are empty should be -removed} -\item{(Optional) .spl_context}{a data.frame describing previously performed -splits which collectively arrived at \code{df}} +\item{df}{a \code{data.frame} of incoming data to be split.} +\item{spl}{a Split object. This is largely an internal detail custom functions will not need to worry about, +but \code{obj_name(spl)}, for example, will give the name of the split as it will appear in paths in the resulting +table.} +\item{vals}{any pre-calculated values. If given non-\code{NULL} values, the values returned should match these. +Should be \code{NULL} in most cases and can usually be ignored.} +\item{labels}{any pre-calculated value labels. Same as above for \code{values}.} +\item{trim}{if \code{TRUE}, resulting splits that are empty are removed.} +\item{(optional) .spl_context}{a \code{data.frame} describing previously performed splits which collectively +arrived at \code{df}.} } -The function must then output a \code{named list} with the following -elements: +The function must then output a named \code{list} with the following elements: \describe{ -\item{values}{The vector of all values corresponding to the splits of -\code{df}} -\item{datasplit}{a list of data.frames representing the groupings of the -actual observations from \code{df}.} -\item{labels}{a character vector giving a string label for each value listed -in the \code{values} element above} -\item{(Optional) extras}{If present, extra arguments are to be passed to summary -and analysis functions whenever they are executed on the corresponding -element of \code{datasplit} or a subset thereof} +\item{values}{the vector of all values corresponding to the splits of \code{df}.} +\item{datasplit}{a list of \code{data.frame}s representing the groupings of the actual observations from \code{df}.} +\item{labels}{a character vector giving a string label for each value listed in the \code{values} element above.} +\item{(optional) extras}{if present, extra arguments are to be passed to summary and analysis functions +whenever they are executed on the corresponding element of \code{datasplit} or a subset thereof.} } -One way to generate custom splitting functions is to wrap existing split -functions and modify either the incoming data before they are called or -their outputs. +One way to generate custom splitting functions is to wrap existing split functions and modify either the incoming +data before they are called or their outputs. } \examples{ @@ -132,6 +113,7 @@ tbl2 # By default sequentially adding layouts results in nesting library(dplyr) + DM_MF <- DM \%>\% filter(SEX \%in\% c("M", "F")) \%>\% mutate(SEX = droplevels(SEX)) diff --git a/man/split_cols_by_multivar.Rd b/man/split_cols_by_multivar.Rd index d223f6710..eb5722766 100644 --- a/man/split_cols_by_multivar.Rd +++ b/man/split_cols_by_multivar.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/colby_constructors.R \name{split_cols_by_multivar} \alias{split_cols_by_multivar} -\title{Associate Multiple Variables with Columns} +\title{Associate multiple variables with columns} \usage{ split_cols_by_multivar( lyt, @@ -15,42 +15,37 @@ split_cols_by_multivar( ) } \arguments{ -\item{lyt}{layout object pre-data used for tabulation} +\item{lyt}{(\code{PreDataTableLayouts})\cr layout object pre-data used for tabulation.} -\item{vars}{character vector. Multiple variable names.} +\item{vars}{(\code{character})\cr vector of variable names.} -\item{split_fun}{function/NULL. custom splitting function See -\code{\link{custom_split_funs}}} +\item{split_fun}{(\code{function} or \code{NULL})\cr custom splitting function. See \link{custom_split_funs}.} -\item{varlabels}{character vector. Labels for \code{vars}} +\item{varlabels}{(\code{character})\cr vector of labels for \code{vars}.} -\item{varnames}{character vector. Names for \code{vars} which will appear in -pathing. When \code{vars} are all unique this will be the variable names. -If not, these will be variable names with suffixes as necessary to enforce +\item{varnames}{(\code{character})\cr vector of names for \code{vars} which will appear in pathing. When \code{vars} are all +unique this will be the variable names. If not, these will be variable names with suffixes as necessary to enforce uniqueness.} -\item{nested}{boolean. Should this layout instruction be applied within the -existing layout structure \emph{if possible} (\code{TRUE}, the default) or as a -new top-level element (`FALSE). Ignored if it would nest a split underneath -analyses, which is not allowed.} +\item{nested}{(\code{logical})\cr whether this layout instruction should be applied within the existing layout structure +\emph{if possible} (\code{TRUE}, the default) or as a new top-level element (\code{FALSE}). Ignored if it would nest a split +underneath analyses, which is not allowed.} -\item{extra_args}{list. Extra arguments to be passed to the tabulation -function. Element position in the list corresponds to the children of this -split. Named elements in the child-specific lists are ignored if they do +\item{extra_args}{(\code{list})\cr extra arguments to be passed to the tabulation function. Element position in the list +corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do not match a formal argument of the tabulation function.} } \value{ -A \code{PreDataTableLayouts} object suitable for passing to further -layouting functions, and to \code{build_table}. +A \code{PreDataTableLayouts} object suitable for passing to further layouting functions, and to \code{\link[=build_table]{build_table()}}. } \description{ -In some cases, the variable to be ultimately analyzed is most naturally -defined on a column, not a row basis. When we need columns to reflect -different variables entirely, rather than different levels of a single -variable, we use \code{split_cols_by_multivar} +In some cases, the variable to be ultimately analyzed is most naturally defined on a column, not a row, basis. +When we need columns to reflect different variables entirely, rather than different levels of a single +variable, we use \code{split_cols_by_multivar}. } \examples{ library(dplyr) + ANL <- DM \%>\% mutate(value = rnorm(n()), pctdiff = runif(n())) ## toy example where we take the mean of the first variable and the diff --git a/man/split_funcs.Rd b/man/split_funcs.Rd index 1082848db..00dc89d1a 100644 --- a/man/split_funcs.Rd +++ b/man/split_funcs.Rd @@ -23,45 +23,39 @@ reorder_split_levels(neworder, newlabels = neworder, drlevels = TRUE) trim_levels_in_group(innervar, drop_outlevs = TRUE) } \arguments{ -\item{excl}{character. Levels to be excluded (they will not be reflected in -the resulting table structure regardless of presence in the data).} +\item{excl}{(\code{character})\cr levels to be excluded (they will not be reflected in the resulting table structure +regardless of presence in the data).} -\item{only}{character. Levels to retain (all others will be dropped).} +\item{only}{(\code{character})\cr levels to retain (all others will be dropped).} -\item{reorder}{logical(1). Should the order of \code{only} be used as the -order of the children of the split. defaults to \code{TRUE}} +\item{reorder}{(\code{flag})\cr whether the order of \code{only} should be used as the order of the children of the +split. Defaults to \code{TRUE}.} -\item{df}{dataset (\code{data.frame} or \code{tibble})} +\item{df}{(\code{data.frame} or \code{tibble})\cr dataset.} -\item{spl}{A Split object defining a partitioning or analysis/tabulation of -the data.} +\item{spl}{(\code{Split})\cr a \code{Split} object defining a partitioning or analysis/tabulation of the data.} -\item{vals}{ANY. For internal use only.} +\item{vals}{(\code{ANY})\cr for internal use only.} -\item{labels}{character. Labels to use for the remaining levels instead of -the existing ones.} +\item{labels}{(\code{character})\cr labels to use for the remaining levels instead of the existing ones.} -\item{trim}{logical(1). Should splits corresponding with 0 observations be -kept when tabulating.} +\item{trim}{(\code{flag})\cr whether splits corresponding with 0 observations should be kept when tabulating.} -\item{neworder}{character. New order or factor levels.} +\item{neworder}{(\code{character})\cr new order of factor levels.} -\item{newlabels}{character. Labels for (new order of) factor levels} +\item{newlabels}{(\code{character})\cr labels for (new order of) factor levels.} -\item{drlevels}{logical(1). Should levels in the data which do not appear in -\code{neworder} be dropped. Defaults to \code{TRUE}} +\item{drlevels}{(\code{flag})\cr whether levels in the data which do not appear in \code{neworder} should be dropped. +Defaults to \code{TRUE}.} -\item{innervar}{character(1). Variable whose factor levels should be trimmed -(e.g., empty levels dropped) \emph{separately within each grouping defined -at this point in the structure}} +\item{innervar}{(\code{string})\cr variable whose factor levels should be trimmed (e.g. empty levels dropped) +\emph{separately within each grouping defined at this point in the structure}.} -\item{drop_outlevs}{logical(1). Should empty levels in the variable being -split on (i.e. the 'outer' variable, not \code{innervar}) be dropped? -Defaults to \code{TRUE}} +\item{drop_outlevs}{(\code{flag})\cr whether empty levels in the variable being split on (i.e. the "outer" +variable, not \code{innervar}) should be dropped. Defaults to \code{TRUE}.} } \value{ -a closure suitable for use as a splitting function (\code{splfun}) -when creating a table layout +A closure suitable for use as a splitting function (\code{splfun}) when creating a table layout. } \description{ Split functions @@ -69,46 +63,35 @@ Split functions \section{Custom Splitting Function Details}{ -User-defined custom split functions can perform any type of computation on -the incoming data provided that they meet the contract for generating -'splits' of the incoming data 'based on' the split object. +User-defined custom split functions can perform any type of computation on the incoming data provided that they +meet the requirements for generating "splits" of the incoming data based on the split object. Split functions are functions that accept: \describe{ -\item{df}{data.frame of incoming data to be split} -\item{spl}{a Split object. this is largely an internal detail custom -functions will not need to worry about, but \code{obj_name(spl)}, for -example, will give the name of the split as it will appear in paths in the -resulting table} -\item{vals}{Any pre-calculated values. If given non-null values, the values -returned should match these. Should be NULL in most cases and can likely be -ignored} -\item{labels}{Any pre-calculated value labels. Same as above for -\code{values}} -\item{trim}{If \code{TRUE}, resulting splits that are empty should be -removed} -\item{(Optional) .spl_context}{a data.frame describing previously performed -splits which collectively arrived at \code{df}} +\item{df}{a \code{data.frame} of incoming data to be split.} +\item{spl}{a Split object. This is largely an internal detail custom functions will not need to worry about, +but \code{obj_name(spl)}, for example, will give the name of the split as it will appear in paths in the resulting +table.} +\item{vals}{any pre-calculated values. If given non-\code{NULL} values, the values returned should match these. +Should be \code{NULL} in most cases and can usually be ignored.} +\item{labels}{any pre-calculated value labels. Same as above for \code{values}.} +\item{trim}{if \code{TRUE}, resulting splits that are empty are removed.} +\item{(optional) .spl_context}{a \code{data.frame} describing previously performed splits which collectively +arrived at \code{df}.} } -The function must then output a \code{named list} with the following -elements: +The function must then output a named \code{list} with the following elements: \describe{ -\item{values}{The vector of all values corresponding to the splits of -\code{df}} -\item{datasplit}{a list of data.frames representing the groupings of the -actual observations from \code{df}.} -\item{labels}{a character vector giving a string label for each value listed -in the \code{values} element above} -\item{(Optional) extras}{If present, extra arguments are to be passed to summary -and analysis functions whenever they are executed on the corresponding -element of \code{datasplit} or a subset thereof} +\item{values}{the vector of all values corresponding to the splits of \code{df}.} +\item{datasplit}{a list of \code{data.frame}s representing the groupings of the actual observations from \code{df}.} +\item{labels}{a character vector giving a string label for each value listed in the \code{values} element above.} +\item{(optional) extras}{if present, extra arguments are to be passed to summary and analysis functions +whenever they are executed on the corresponding element of \code{datasplit} or a subset thereof.} } -One way to generate custom splitting functions is to wrap existing split -functions and modify either the incoming data before they are called or -their outputs. +One way to generate custom splitting functions is to wrap existing split functions and modify either the incoming +data before they are called or their outputs. } \examples{ @@ -134,6 +117,7 @@ lyt <- basic_table() \%>\% tbl <- build_table(lyt, DM) tbl + lyt <- basic_table() \%>\% split_cols_by("ARM") \%>\% split_rows_by("SEX", split_fun = drop_split_levels) \%>\% @@ -141,6 +125,7 @@ lyt <- basic_table() \%>\% tbl <- build_table(lyt, DM) tbl + lyt <- basic_table() \%>\% split_cols_by("ARM") \%>\% split_rows_by("SEX", split_fun = drop_and_remove_levels(c("M", "U"))) \%>\% @@ -148,4 +133,5 @@ lyt <- basic_table() \%>\% tbl <- build_table(lyt, DM) tbl + } diff --git a/man/split_rows_by.Rd b/man/split_rows_by.Rd index 1f1177e7c..bb334b4b3 100644 --- a/man/split_rows_by.Rd +++ b/man/split_rows_by.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/colby_constructors.R \name{split_rows_by} \alias{split_rows_by} -\title{Add Rows according to levels of a variable} +\title{Add rows according to levels of a variable} \usage{ split_rows_by( lyt, @@ -22,116 +22,92 @@ split_rows_by( ) } \arguments{ -\item{lyt}{layout object pre-data used for tabulation} +\item{lyt}{(\code{PreDataTableLayouts})\cr layout object pre-data used for tabulation.} -\item{var}{string, variable name} +\item{var}{(\code{string})\cr variable name.} -\item{labels_var}{string, name of variable containing labels to be displayed -for the values of \code{var}} +\item{labels_var}{(\code{string})\cr name of variable containing labels to be displayed for the values of \code{var}.} -\item{split_label}{string. Label string to be associated with the table -generated by the split. Not to be confused with labels assigned to each -child (which are based on the data and type of split during tabulation).} +\item{split_label}{(\code{string})\cr label to be associated with the table generated by the split. Not to be confused +with labels assigned to each child (which are based on the data and type of split during tabulation).} -\item{split_fun}{function/NULL. custom splitting function See -\code{\link{custom_split_funs}}} +\item{split_fun}{(\code{function} or \code{NULL})\cr custom splitting function. See \link{custom_split_funs}.} -\item{format}{\code{FormatSpec}. Format associated with this split. Formats can be -declared via strings (\code{"xx.x"}) or function. In cases such as -\code{analyze} calls, they can character vectors or lists of functions.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr format associated with this split. Formats can be declared via +strings (\code{"xx.x"}) or function. In cases such as \code{analyze} calls, they can be character vectors or lists of +functions. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for a list of all available format strings.} -\item{na_str}{character(1). String that should be displayed when the value of \code{x} is missing. -Defaults to \code{"NA"}.} +\item{na_str}{(\code{string})\cr string that should be displayed when the value of \code{x} is missing. Defaults to \code{"NA"}.} -\item{nested}{boolean. Should this layout instruction be applied within the -existing layout structure \emph{if possible} (\code{TRUE}, the default) or as a -new top-level element (`FALSE). Ignored if it would nest a split underneath -analyses, which is not allowed.} +\item{nested}{(\code{logical})\cr whether this layout instruction should be applied within the existing layout structure +\emph{if possible} (\code{TRUE}, the default) or as a new top-level element (\code{FALSE}). Ignored if it would nest a split +underneath analyses, which is not allowed.} -\item{child_labels}{string. One of \code{"default"}, \code{"visible"}, -\code{"hidden"}. What should the display behavior be for the labels (i.e. -label rows) of the children of this split. Defaults to \code{"default"} -which flags the label row as visible only if the child has 0 content rows.} +\item{child_labels}{(\code{string})\cr the display behavior for the labels (i.e. label rows) of the children of this +split. Accepts \code{"default"}, \code{"visible"}, and \code{"hidden"}. Defaults to \code{"default"} which flags the label row as +visible only if the child has 0 content rows.} -\item{label_pos}{character(1). Location the variable label should be -displayed, Accepts \code{"hidden"} (default for non-analyze row splits), \code{"visible"}, -\code{"topleft"}, and - for analyze splits only - \code{"default"}. For analyze calls, -\code{"default"} indicates that the variable should be visible if and only if -multiple variables are analyzed at the same level of nesting.} +\item{label_pos}{(\code{string})\cr location where the variable label should be displayed. Accepts \code{"hidden"} +(default for non-analyze row splits), \code{"visible"}, \code{"topleft"}, and \code{"default"} (for analyze splits only). For +\code{analyze} calls, \code{"default"} indicates that the variable should be visible if and only if multiple variables are +analyzed at the same level of nesting.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} -\item{page_by}{logical(1). Should pagination be forced between different -children resulting form this split. An error will rise if the selected split -does not contain at least one value that is not \code{NA}.} +\item{page_by}{(\code{flag})\cr whether pagination should be forced between different children resulting from this +split. An error will occur if the selected split does not contain at least one value that is not \code{NA}.} -\item{page_prefix}{character(1). Prefix, to be appended with the split value, -when forcing pagination between the children of this split/table} +\item{page_prefix}{(\code{string})\cr prefix to be appended with the split value when forcing pagination between +the children of a split/table.} -\item{section_div}{character(1). String which should be repeated as a section -divider after each group defined by this split instruction, or -\code{NA_character_} (the default) for no section divider.} +\item{section_div}{(\code{string})\cr string which should be repeated as a section divider after each group defined +by this split instruction, or \code{NA_character_} (the default) for no section divider.} } \value{ -A \code{PreDataTableLayouts} object suitable for passing to further -layouting functions, and to \code{build_table}. +A \code{PreDataTableLayouts} object suitable for passing to further layouting functions, and to \code{\link[=build_table]{build_table()}}. } \description{ -Add Rows according to levels of a variable +Add rows according to levels of a variable } \note{ -If \code{var} is a factor with empty unobserved levels and -\code{labels_var} is specified, it must also be a factor -with the same number of levels as \code{var}. Currently the -error that occurs when this is not the case is not very informative, -but that will change in the future. +If \code{var} is a factor with empty unobserved levels and \code{labels_var} is specified, it must also be a factor +with the same number of levels as \code{var}. Currently the error that occurs when this is not the case is not very +informative, but that will change in the future. } \section{Custom Splitting Function Details}{ -User-defined custom split functions can perform any type of computation on -the incoming data provided that they meet the contract for generating -'splits' of the incoming data 'based on' the split object. +User-defined custom split functions can perform any type of computation on the incoming data provided that they +meet the requirements for generating "splits" of the incoming data based on the split object. Split functions are functions that accept: \describe{ -\item{df}{data.frame of incoming data to be split} -\item{spl}{a Split object. this is largely an internal detail custom -functions will not need to worry about, but \code{obj_name(spl)}, for -example, will give the name of the split as it will appear in paths in the -resulting table} -\item{vals}{Any pre-calculated values. If given non-null values, the values -returned should match these. Should be NULL in most cases and can likely be -ignored} -\item{labels}{Any pre-calculated value labels. Same as above for -\code{values}} -\item{trim}{If \code{TRUE}, resulting splits that are empty should be -removed} -\item{(Optional) .spl_context}{a data.frame describing previously performed -splits which collectively arrived at \code{df}} +\item{df}{a \code{data.frame} of incoming data to be split.} +\item{spl}{a Split object. This is largely an internal detail custom functions will not need to worry about, +but \code{obj_name(spl)}, for example, will give the name of the split as it will appear in paths in the resulting +table.} +\item{vals}{any pre-calculated values. If given non-\code{NULL} values, the values returned should match these. +Should be \code{NULL} in most cases and can usually be ignored.} +\item{labels}{any pre-calculated value labels. Same as above for \code{values}.} +\item{trim}{if \code{TRUE}, resulting splits that are empty are removed.} +\item{(optional) .spl_context}{a \code{data.frame} describing previously performed splits which collectively +arrived at \code{df}.} } -The function must then output a \code{named list} with the following -elements: +The function must then output a named \code{list} with the following elements: \describe{ -\item{values}{The vector of all values corresponding to the splits of -\code{df}} -\item{datasplit}{a list of data.frames representing the groupings of the -actual observations from \code{df}.} -\item{labels}{a character vector giving a string label for each value listed -in the \code{values} element above} -\item{(Optional) extras}{If present, extra arguments are to be passed to summary -and analysis functions whenever they are executed on the corresponding -element of \code{datasplit} or a subset thereof} +\item{values}{the vector of all values corresponding to the splits of \code{df}.} +\item{datasplit}{a list of \code{data.frame}s representing the groupings of the actual observations from \code{df}.} +\item{labels}{a character vector giving a string label for each value listed in the \code{values} element above.} +\item{(optional) extras}{if present, extra arguments are to be passed to summary and analysis functions +whenever they are executed on the corresponding element of \code{datasplit} or a subset thereof.} } -One way to generate custom splitting functions is to wrap existing split -functions and modify either the incoming data before they are called or -their outputs. +One way to generate custom splitting functions is to wrap existing split functions and modify either the incoming +data before they are called or their outputs. } \examples{ @@ -165,6 +141,7 @@ lyt3 <- basic_table() \%>\% lyt3 library(dplyr) + DM2 <- DM \%>\% filter(SEX \%in\% c("M", "F")) \%>\% mutate( diff --git a/man/split_rows_by_multivar.Rd b/man/split_rows_by_multivar.Rd index ed14d6a19..ba290e4d3 100644 --- a/man/split_rows_by_multivar.Rd +++ b/man/split_rows_by_multivar.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/colby_constructors.R \name{split_rows_by_multivar} \alias{split_rows_by_multivar} -\title{Associate Multiple Variables with Rows} +\title{Associate multiple variables with rows} \usage{ split_rows_by_multivar( lyt, @@ -20,53 +20,44 @@ split_rows_by_multivar( ) } \arguments{ -\item{lyt}{layout object pre-data used for tabulation} +\item{lyt}{(\code{PreDataTableLayouts})\cr layout object pre-data used for tabulation.} -\item{vars}{character vector. Multiple variable names.} +\item{vars}{(\code{character})\cr vector of variable names.} -\item{split_fun}{function/NULL. custom splitting function See -\code{\link{custom_split_funs}}} +\item{split_fun}{(\code{function} or \code{NULL})\cr custom splitting function. See \link{custom_split_funs}.} -\item{split_label}{string. Label string to be associated with the table -generated by the split. Not to be confused with labels assigned to each -child (which are based on the data and type of split during tabulation).} +\item{split_label}{(\code{string})\cr label to be associated with the table generated by the split. Not to be confused +with labels assigned to each child (which are based on the data and type of split during tabulation).} -\item{varlabels}{character vector. Labels for \code{vars}} +\item{varlabels}{(\code{character})\cr vector of labels for \code{vars}.} -\item{format}{\code{FormatSpec}. Format associated with this split. Formats can be -declared via strings (\code{"xx.x"}) or function. In cases such as -\code{analyze} calls, they can character vectors or lists of functions.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr format associated with this split. Formats can be declared via +strings (\code{"xx.x"}) or function. In cases such as \code{analyze} calls, they can be character vectors or lists of +functions. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for a list of all available format strings.} -\item{na_str}{character(1). String that should be displayed when the value of \code{x} is missing. -Defaults to \code{"NA"}.} +\item{na_str}{(\code{string})\cr string that should be displayed when the value of \code{x} is missing. Defaults to \code{"NA"}.} -\item{nested}{boolean. Should this layout instruction be applied within the -existing layout structure \emph{if possible} (\code{TRUE}, the default) or as a -new top-level element (`FALSE). Ignored if it would nest a split underneath -analyses, which is not allowed.} +\item{nested}{(\code{logical})\cr whether this layout instruction should be applied within the existing layout structure +\emph{if possible} (\code{TRUE}, the default) or as a new top-level element (\code{FALSE}). Ignored if it would nest a split +underneath analyses, which is not allowed.} -\item{child_labels}{string. One of \code{"default"}, \code{"visible"}, -\code{"hidden"}. What should the display behavior be for the labels (i.e. -label rows) of the children of this split. Defaults to \code{"default"} -which flags the label row as visible only if the child has 0 content rows.} +\item{child_labels}{(\code{string})\cr the display behavior for the labels (i.e. label rows) of the children of this +split. Accepts \code{"default"}, \code{"visible"}, and \code{"hidden"}. Defaults to \code{"default"} which flags the label row as +visible only if the child has 0 content rows.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} -\item{section_div}{character(1). String which should be repeated as a section -divider after each group defined by this split instruction, or -\code{NA_character_} (the default) for no section divider.} +\item{section_div}{(\code{string})\cr string which should be repeated as a section divider after each group defined +by this split instruction, or \code{NA_character_} (the default) for no section divider.} -\item{extra_args}{list. Extra arguments to be passed to the tabulation -function. Element position in the list corresponds to the children of this -split. Named elements in the child-specific lists are ignored if they do +\item{extra_args}{(\code{list})\cr extra arguments to be passed to the tabulation function. Element position in the list +corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do not match a formal argument of the tabulation function.} } \value{ -A \code{PreDataTableLayouts} object suitable for passing to further -layouting functions, and to \code{build_table}. +A \code{PreDataTableLayouts} object suitable for passing to further layouting functions, and to \code{\link[=build_table]{build_table()}}. } \description{ When we need rows to reflect different variables rather than different @@ -84,6 +75,6 @@ tbl } \seealso{ -\code{\link[=split_rows_by]{split_rows_by()}} for typical row splitting, and -\code{\link[=split_cols_by_multivar]{split_cols_by_multivar()}} to perform the same type of split on a column basis. +\code{\link[=split_rows_by]{split_rows_by()}} for typical row splitting, and \code{\link[=split_cols_by_multivar]{split_cols_by_multivar()}} to perform the same type of +split on a column basis. } diff --git a/man/summarize_row_groups.Rd b/man/summarize_row_groups.Rd index 059141a6f..79f0bed0e 100644 --- a/man/summarize_row_groups.Rd +++ b/man/summarize_row_groups.Rd @@ -16,60 +16,51 @@ summarize_row_groups( ) } \arguments{ -\item{lyt}{layout object pre-data used for tabulation} +\item{lyt}{(\code{PreDataTableLayouts})\cr layout object pre-data used for tabulation.} -\item{var}{string, variable name} +\item{var}{(\code{string})\cr variable name.} -\item{label_fstr}{string. An \code{sprintf} style format string containing. For -non-comparison splits, it can contain up to one \code{"\%s"} which takes -the current split value and generates the row/column label. -Comparison-based splits it can contain up to two \code{"\%s"}.} +\item{label_fstr}{(\code{string})\cr a \code{sprintf} style format string. For non-comparison splits, it can contain up to +one \code{"\\\%s"} which takes the current split value and generates the row/column label. For comparison-based splits +it can contain up to two \code{"\\\%s"}.} -\item{format}{\code{FormatSpec}. Format associated with this split. Formats can be -declared via strings (\code{"xx.x"}) or function. In cases such as -\code{analyze} calls, they can character vectors or lists of functions.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr format associated with this split. Formats can be declared via +strings (\code{"xx.x"}) or function. In cases such as \code{analyze} calls, they can be character vectors or lists of +functions. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for a list of all available format strings.} -\item{na_str}{character(1). String that should be displayed when the value of \code{x} is missing. -Defaults to \code{"NA"}.} +\item{na_str}{(\code{string})\cr string that should be displayed when the value of \code{x} is missing. Defaults to \code{"NA"}.} -\item{cfun}{list/function/NULL. tabulation function(s) for creating content -rows. Must accept \code{x} or \code{df} as first parameter. Must accept -\code{labelstr} as the second argument. Can optionally accept all optional -arguments accepted by analysis functions. See \code{\link{analyze}}.} +\item{cfun}{(\code{list}, \code{function}, or \code{NULL})\cr tabulation function(s) for creating content rows. Must accept \code{x} +or \code{df} as first parameter. Must accept \code{labelstr} as the second argument. Can optionally accept all optional +arguments accepted by analysis functions. See \code{\link[=analyze]{analyze()}}.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} -\item{extra_args}{list. Extra arguments to be passed to the tabulation -function. Element position in the list corresponds to the children of this -split. Named elements in the child-specific lists are ignored if they do +\item{extra_args}{(\code{list})\cr extra arguments to be passed to the tabulation function. Element position in the list +corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do not match a formal argument of the tabulation function.} } \value{ -A \code{PreDataTableLayouts} object suitable for passing to further -layouting functions, and to \code{build_table}. +A \code{PreDataTableLayouts} object suitable for passing to further layouting functions, and to \code{\link[=build_table]{build_table()}}. } \description{ Add a content row of summary counts } \details{ -If \code{format} expects 1 value (i.e. it is specified as a format string -and \code{xx} appears for two values (i.e. \code{xx} appears twice in the -format string) or is specified as a function, then both raw and percent of -column total counts are calculated. If \code{format} is a format string where -\code{xx} appears only one time, only raw counts are used. - -\code{cfun} must accept \code{x} or \code{df} as its first argument. For the \code{df} argument -\code{cfun} will receive the subset \code{data.frame} corresponding with the row- -and column-splitting for the cell being calculated. Must accept \code{labelstr} as -the second parameter, which accepts the \code{label} of the level of the parent -split currently being summarized. Can additionally take any optional argument -supported by analysis functions. (see \code{\link{analyze}}). - -In addition, if complex custom functions are needed, we suggest checking the -available \link{additional_fun_params} that apply here as for \code{afun}. +If \code{format} expects 1 value (i.e. it is specified as a format string and \code{xx} appears for two values +(i.e. \code{xx} appears twice in the format string) or is specified as a function, then both raw and percent of +column total counts are calculated. If \code{format} is a format string where \code{xx} appears only one time, only +raw counts are used. + +\code{cfun} must accept \code{x} or \code{df} as its first argument. For the \code{df} argument \code{cfun} will receive the subset +\code{data.frame} corresponding with the row- and column-splitting for the cell being calculated. Must accept +\code{labelstr} as the second parameter, which accepts the \code{label} of the level of the parent split currently +being summarized. Can additionally take any optional argument supported by analysis functions. (see \code{\link[=analyze]{analyze()}}). + +In addition, if complex custom functions are needed, we suggest checking the available \link{additional_fun_params} +that can be used in \code{cfun}. } \examples{ DM2 <- subset(DM, COUNTRY \%in\% c("USA", "CAN", "CHN")) @@ -86,7 +77,6 @@ tbl row_paths_summary(tbl) # summary count is a content table - ## use a cfun and extra_args to customize summarization ## behavior sfun <- function(x, labelstr, trim) { diff --git a/man/summarize_rows.Rd b/man/summarize_rows.Rd deleted file mode 100644 index 18a96da84..000000000 --- a/man/summarize_rows.Rd +++ /dev/null @@ -1,17 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/summary.R -\name{summarize_rows} -\alias{summarize_rows} -\title{summarize_rows} -\usage{ -summarize_rows(obj) -} -\arguments{ -\item{obj}{\code{VTableTree}.} -} -\value{ -A data.frame summarizing the rows in \code{obj}. -} -\description{ -\code{summarize_rows} is deprecated in favor of \code{make_row_df}. -} diff --git a/man/tabclasses.Rd b/man/tabclasses.Rd index 69bd45993..7ec9e1764 100644 --- a/man/tabclasses.Rd +++ b/man/tabclasses.Rd @@ -59,81 +59,68 @@ TableTree( ) } \arguments{ -\item{kids}{list. List of direct children.} +\item{kids}{(\code{list})\cr list of direct children.} -\item{name}{character(1). Name of the split/table/row being created. Defaults -to same as the corresponding label, but is not required to be.} +\item{name}{(\code{string})\cr name of the split/table/row being created. Defaults to the value of the +corresponding label, but is not required to be.} -\item{lev}{integer. Nesting level (roughly, indentation level in practical -terms).} +\item{lev}{(\code{integer(1)})\cr nesting level (roughly, indentation level in practical terms).} -\item{label}{character(1). A label (not to be confused with the name) for the -object/structure.} +\item{label}{(\code{string})\cr a label (not to be confused with the name) for the object/structure.} -\item{labelrow}{\code{LabelRow}. The \code{LabelRow} object to assign to this Table. -Constructed from \code{label} by default if not specified.} +\item{labelrow}{(\code{LabelRow})\cr the \code{LabelRow} object to assign to the table. Constructed from \code{label} by default +if not specified.} -\item{rspans}{data.frame. Currently stored but otherwise ignored.} +\item{rspans}{(\code{data.frame})\cr currently stored but otherwise ignored.} -\item{cinfo}{\code{InstantiatedColumnInfo} (or NULL). Column structure for the -object being created.} +\item{cinfo}{(\code{InstantiatedColumnInfo} or \code{NULL})\cr column structure for the object being created.} -\item{iscontent}{logical. Is the \code{TableTree}/\code{ElementaryTable} being constructed -the content table for another \code{TableTree}.} +\item{iscontent}{(\code{flag})\cr whether the \code{TableTree}/\code{ElementaryTable} is being constructed as the content +table for another \code{TableTree}.} -\item{var}{string, variable name} +\item{var}{(\code{string})\cr variable name.} -\item{format}{\code{FormatSpec}. Format associated with this split. Formats can be -declared via strings (\code{"xx.x"}) or function. In cases such as -\code{analyze} calls, they can character vectors or lists of functions.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr format associated with this split. Formats can be declared via +strings (\code{"xx.x"}) or function. In cases such as \code{analyze} calls, they can be character vectors or lists of +functions. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for a list of all available format strings.} -\item{na_str}{character(1). String that should be displayed when the value of \code{x} is missing. -Defaults to \code{"NA"}.} +\item{na_str}{(\code{string})\cr string that should be displayed when the value of \code{x} is missing. Defaults to \code{"NA"}.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} -\item{title}{character(1). Main title (\code{\link[=main_title]{main_title()}}) is a single string. -Ignored for subtables.} +\item{title}{(\code{string})\cr single string to use as main title (\code{\link[=main_title]{main_title()}}). Ignored for subtables.} -\item{subtitles}{character. Subtitles (\code{\link[=subtitles]{subtitles()}}) can be vector of strings, where -every element is printed in a separate line. Ignored for subtables.} +\item{subtitles}{(\code{character})\cr a vector of strings to use as subtitles (\code{\link[=subtitles]{subtitles()}}), where every element is +printed on a separate line. Ignored for subtables.} -\item{main_footer}{character. Main global (non-referential) footer materials -(\code{\link[=main_footer]{main_footer()}}). If it is a vector of strings, they will be printed on separate -lines.} +\item{main_footer}{(\code{character})\cr a vector of strings to use as main global (non-referential) footer materials +(\code{\link[=main_footer]{main_footer()}}), where every element is printed on a separate line.} -\item{prov_footer}{character. Provenance-related global footer materials -(\code{\link[=prov_footer]{prov_footer()}}). It can be also a vector of strings, printed on different lines. -Generally should not be modified by hand.} +\item{prov_footer}{(\code{character})\cr a vector of strings to use as provenance-related global footer materials +(\code{\link[=prov_footer]{prov_footer()}}), where every element is printed on a separate line.} -\item{header_section_div}{character(1). String which will be used to divide the header -from the table. See \code{\link[=header_section_div]{header_section_div()}} for getter and setter of these. -Please consider changing last element of \code{\link[=section_div]{section_div()}} when concatenating -tables that need a divider between them.} +\item{header_section_div}{(\code{string})\cr string which will be used to divide the header from the table. See +\code{\link[=header_section_div]{header_section_div()}} for the associated getter and setter. Please consider changing last element of +\code{\link[=section_div]{section_div()}} when concatenating tables that require a divider between them.} -\item{hsep}{character(1). Set of character(s) to be repeated as the separator -between the header and body of the table when rendered as text. Defaults to -a connected horizontal line (unicode 2014) in locals that use a UTF -charset, and to \code{-} elsewhere (with a once per session warning). See -\code{\link[formatters:default_horizontal_sep]{formatters::set_default_hsep()}} for further information.} +\item{hsep}{(\code{string})\cr set of characters to be repeated as the separator between the header and body of +the table when rendered as text. Defaults to a connected horizontal line (unicode 2014) in locals that use a UTF +charset, and to \code{-} elsewhere (with a once per session warning). See \code{\link[formatters:default_horizontal_sep]{formatters::set_default_hsep()}} for further +information.} -\item{trailing_section_div}{character(1). String which will be used as a section -divider after the printing of the last row contained in this (sub)-table, -unless that row is also the last table row to be printed overall, or -\code{NA_character_} for none (the default). When generated via layouting, this -would correspond to the \code{section_div} of the split under which this table -represents a single facet.} +\item{trailing_section_div}{(\code{string})\cr string which will be used as a section divider after the printing +of the last row contained in this (sub)table, unless that row is also the last table row to be printed overall, +or \code{NA_character_} for none (the default). When generated via layouting, this would correspond to the +\code{section_div} of the split under which this table represents a single facet.} -\item{inset}{numeric(1). Number of spaces to inset the table header, table -body, referential footnotes, and main_footer, as compared to alignment -of title, subtitle, and provenance footer. Defaults to 0 (no inset).} +\item{inset}{(\code{numeric(1)})\cr number of spaces to inset the table header, table body, referential footnotes, and +main_footer, as compared to alignment of title, subtitle, and provenance footer. Defaults to 0 (no inset).} -\item{cont}{\code{ElementaryTable}. Content table.} +\item{cont}{(\code{ElementaryTable})\cr content table.} -\item{page_title}{character. Page specific title(s).} +\item{page_title}{(\code{character})\cr page-specific title(s).} } \value{ A formal object representing a populated table. @@ -141,7 +128,7 @@ A formal object representing a populated table. \description{ \code{TableTree} classes -Table Constructors and Classes +Table constructors and classes } \author{ Gabriel Becker diff --git a/man/table_shell.Rd b/man/table_shell.Rd index 891298d14..6be8499db 100644 --- a/man/table_shell.Rd +++ b/man/table_shell.Rd @@ -24,38 +24,34 @@ table_shell_str( ) } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\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{col_gap}{numeric(1). Space (in characters) between columns} +\item{col_gap}{(\code{numeric(1)})\cr space (in characters) between columns.} -\item{hsep}{character(1). Characters to repeat to create -header/body separator line. If \code{NULL}, the object value will be -used. If \code{" "}, an empty separator will be printed. Check \code{\link[formatters:default_hsep]{default_hsep()}} -for more information.} +\item{hsep}{(\code{string})\cr character to repeat to create header/body separator line. If +\code{NULL}, the object value will be used. If \code{" "}, an empty separator will be printed. See +\code{\link[formatters:default_hsep]{default_hsep()}} for more information.} -\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}.} } \value{ -for \code{table_shell_str} the string representing the table shell, for \code{table_shell}, -\code{NULL}, as the function is called for the side effect of printing the shell to the console. +\itemize{ +\item \code{table_shell} returns \code{NULL}, as the function is called for the side effect of printing the shell to the console. +\item \code{table_shell_str} returns the string representing the table shell. +} } \description{ -A table shell is a rendering of the table which maintains the structure, but does not -display the values, rather displaying the formatting instructions for each cell. +A table shell is a rendering of the table which maintains the structure, but does not display the values, rather +displaying the formatting instructions for each cell. } \examples{ library(dplyr) diff --git a/man/table_structure.Rd b/man/table_structure.Rd index 5ff781050..a8c344d8a 100644 --- a/man/table_structure.Rd +++ b/man/table_structure.Rd @@ -2,21 +2,20 @@ % Please edit documentation in R/summary.R \name{table_structure} \alias{table_structure} -\title{Summarize Table} +\title{Summarize table} \usage{ table_structure(x, detail = c("subtable", "row")) } \arguments{ -\item{x}{a table object} +\item{x}{(\code{VTableTree})\cr a table object.} -\item{detail}{either \code{row} or \code{subtable}} +\item{detail}{(\code{string})\cr either \code{row} or \code{subtable}.} } \value{ -currently no return value. Called for the side-effect of printing a -row- or subtable-structure summary of \code{x}. +No return value. Called for the side-effect of printing a row- or subtable-structure summary of \code{x}. } \description{ -Summarize Table +Summarize table } \examples{ library(dplyr) @@ -42,4 +41,5 @@ row_paths(tbl) table_structure(tbl) table_structure(tbl, detail = "row") + } diff --git a/man/top_left.Rd b/man/top_left.Rd index 94ca3eea8..6327f2818 100644 --- a/man/top_left.Rd +++ b/man/top_left.Rd @@ -9,7 +9,7 @@ \alias{top_left<-,VTableTree-method} \alias{top_left<-,InstantiatedColumnInfo-method} \alias{top_left<-,PreDataTableLayouts-method} -\title{Top Left Material (Experimental)} +\title{Top left material} \usage{ top_left(obj) @@ -28,16 +28,16 @@ top_left(obj) <- value \S4method{top_left}{PreDataTableLayouts}(obj) <- value } \arguments{ -\item{obj}{ANY. The object for the accessor to access or modify} +\item{obj}{(\code{ANY})\cr the object for the accessor to access or modify.} -\item{value}{The new value} +\item{value}{(\code{ANY})\cr the new value.} } \value{ -A character vector representing the top-left material of \code{obj} (or -\code{obj} after modification, in the case of the setter). +A character vector representing the top-left material of \code{obj} (or \code{obj} after modification, in the +case of the setter). } \description{ -A \code{TableTree} object can have \emph{top left material} which is a sequence -of strings which are printed in the area of the table between the column header display -and the label of the first row. These functions access and modify that material. +A \code{TableTree} object can have \emph{top left material} which is a sequence of strings which are printed in the +area of the table between the column header display and the label of the first row. These functions access +and modify that material. } diff --git a/man/tostring.Rd b/man/tostring.Rd index 05903fbc1..f5e53f4b1 100644 --- a/man/tostring.Rd +++ b/man/tostring.Rd @@ -1,8 +1,8 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/tt_toString.R -\name{tostring} -\alias{tostring} +\name{toString,VTableTree-method} \alias{toString,VTableTree-method} +\alias{tostring} \title{Convert an \code{rtable} object to a string} \usage{ \S4method{toString}{VTableTree}( @@ -16,51 +16,43 @@ ) } \arguments{ -\item{x}{ANY. Object to be prepared for rendering.} +\item{x}{(\code{ANY})\cr object to be prepared for rendering.} -\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{col_gap}{numeric(1). Space (in characters) between columns} +\item{col_gap}{(\code{numeric(1)})\cr space (in characters) between columns.} -\item{hsep}{character(1). Characters to repeat to create -header/body separator line. If \code{NULL}, the object value will be -used. If \code{" "}, an empty separator will be printed. Check \code{\link[formatters:default_hsep]{default_hsep()}} -for more information.} +\item{hsep}{(\code{string})\cr character to repeat to create header/body separator line. If +\code{NULL}, the object value will be used. If \code{" "}, an empty separator will be printed. See +\code{\link[formatters:default_hsep]{default_hsep()}} for more information.} -\item{indent_size}{numeric(1). Number of spaces to use per indent level. -Defaults to 2} +\item{indent_size}{(\code{numeric(1)})\cr number of spaces to use per indent level. Defaults to 2.} -\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}.} } \value{ -a string representation of \code{x} as it appears when printed. +A string representation of \code{x} as it appears when printed. } \description{ -Transform a complex object into a string representation ready -to be printed or written to a plain-text file +Transform a complex object into a string representation ready to be printed or written +to a plain-text file. -All objects that are printed to console pass by \code{toString}. This function allows -fundamental formatting specifications for the final output, like column widths and -relative wrapping (\code{width}), title and footer wrapping (\code{tf_wrap = TRUE} and -\code{max_width}), or horizontal separator character (e.g. \code{hsep = "+"}). +All objects that are printed to console pass via \code{toString}. This function allows +fundamental formatting specifications to be applied to final output, like column widths +and relative wrapping (\code{width}), title and footer wrapping (\code{tf_wrap = TRUE} and +\code{max_width}), and horizontal separator character (e.g. \code{hsep = "+"}). } \details{ -Manual insertion of newlines is not supported when \code{tf_wrap} is on -and will result in a warning and undefined wrapping behavior. Passing -vectors of already split strings remains supported, however in this -case each string is word-wrapped separately with the behavior -described above. +Manual insertion of newlines is not supported when \code{tf_wrap = TRUE} and will result in a warning and +undefined wrapping behavior. Passing vectors of already split strings remains supported, however in this +case each string is word-wrapped separately with the behavior described above. } \examples{ library(dplyr) @@ -78,6 +70,7 @@ lyt <- basic_table() \%>\% tbl <- build_table(lyt, iris2) cat(toString(tbl, col_gap = 3)) + } \seealso{ \code{\link[formatters:wrap_string]{wrap_string()}} diff --git a/man/tree_children.Rd b/man/tree_children.Rd index 489575dff..048f1c23a 100644 --- a/man/tree_children.Rd +++ b/man/tree_children.Rd @@ -3,20 +3,20 @@ \name{tree_children} \alias{tree_children} \alias{tree_children<-} -\title{Retrieve or set the direct children of a Tree-style object} +\title{Retrieve or set the direct children of a tree-style object} \usage{ tree_children(x) tree_children(x) <- value } \arguments{ -\item{x}{An object with a Tree structure} +\item{x}{(\code{TableTree} or \code{ElementaryTable})\cr an object with a tree structure.} -\item{value}{New list of children.} +\item{value}{(\code{list})\cr new list of children.} } \value{ -List of direct children of \code{x} +A list of direct children of \code{x}. } \description{ -Retrieve or set the direct children of a Tree-style object +Retrieve or set the direct children of a tree-style object } diff --git a/man/trim_levels_in_facets.Rd b/man/trim_levels_in_facets.Rd index e6a22394b..5d75540e8 100644 --- a/man/trim_levels_in_facets.Rd +++ b/man/trim_levels_in_facets.Rd @@ -2,23 +2,21 @@ % Please edit documentation in R/make_split_fun.R \name{trim_levels_in_facets} \alias{trim_levels_in_facets} -\title{Trim Levels of Another Variable From Each Facet (Postprocessing split step)} +\title{Trim levels of another variable from each facet (post-processing split step)} \usage{ trim_levels_in_facets(innervar) } \arguments{ -\item{innervar}{character. The variable(s) to trim (remove -unobserved levels) independently within each facet.} +\item{innervar}{(\code{character})\cr the variable(s) to trim (remove unobserved levels) independently within each facet.} } \value{ -a function suitable for use in the \code{pre} -(list) argument of \code{make_split_fun} +A function suitable for use in the \code{pre} (list) argument of \code{make_split_fun}. } \description{ -Trim Levels of Another Variable From Each Facet (Postprocessing split step) +Trim levels of another variable from each facet (post-processing split step) } \seealso{ -make_split_fun +\code{\link[=make_split_fun]{make_split_fun()}} Other make_custom_split: \code{\link{add_combo_facet}()}, diff --git a/man/trim_levels_to_map.Rd b/man/trim_levels_to_map.Rd index 6b07c55bc..cde31f643 100644 --- a/man/trim_levels_to_map.Rd +++ b/man/trim_levels_to_map.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/split_funs.R \name{trim_levels_to_map} \alias{trim_levels_to_map} -\title{Trim Levels to map} +\title{Trim levels to map} \usage{ trim_levels_to_map(map = NULL) } @@ -14,26 +14,22 @@ those present in the data but not associated with this split or any parents of it.} } \value{ -a fun +A function that can be used as a split function. } \description{ -This split function constructor creates a split function which trims -levels of a variable to reflect restrictions on the possible -combinations of two or more variables which are split by -(along the same axis) within a layout. +This split function constructor creates a split function which trims levels of a variable to reflect restrictions +on the possible combinations of two or more variables which the data is split by (along the same axis) within a +layout. } \details{ -When splitting occurs, the map is subset to the values of all -previously performed splits. The levels of the variable being split are -then pruned to only those still present within this subset of the map -representing the current hierarchical splitting context. +When splitting occurs, the map is subset to the values of all previously performed splits. The levels of the +variable being split are then pruned to only those still present within this subset of the map representing the +current hierarchical splitting context. -Splitting is then performed via the \code{\link{keep_split_levels}} split -function. +Splitting is then performed via the \code{\link[=keep_split_levels]{keep_split_levels()}} split function. -Each resulting element of the partition is then further trimmed by pruning -values of any remaining variables specified in the map to those values -allowed under the combination of the previous and current split. +Each resulting element of the partition is then further trimmed by pruning values of any remaining variables +specified in the map to those values allowed under the combination of the previous and current split. } \examples{ map <- data.frame( @@ -48,6 +44,7 @@ lyt <- basic_table() \%>\% split_rows_by("PARAMCD", split_fun = trim_levels_to_map(map = map)) \%>\% analyze("ANRIND") tbl <- build_table(lyt, ex_adlb) + } \seealso{ \code{\link[=trim_levels_in_group]{trim_levels_in_group()}} diff --git a/man/trim_prune_funs.Rd b/man/trim_prune_funs.Rd index b1ccb5876..a03303df4 100644 --- a/man/trim_prune_funs.Rd +++ b/man/trim_prune_funs.Rd @@ -7,7 +7,7 @@ \alias{prune_empty_level} \alias{prune_zeros_only} \alias{low_obs_pruner} -\title{Trimming and Pruning Criteria} +\title{Trimming and pruning criteria} \usage{ all_zero_or_na(tr) @@ -22,62 +22,48 @@ prune_zeros_only(tt) low_obs_pruner(min, type = c("sum", "mean")) } \arguments{ -\item{tr}{\code{TableRow} (or related class). A \code{TableRow} object representing a -single row within a populated table.} +\item{tr}{(\code{TableRow} or related class)\cr a \code{TableRow} object representing a single row within a populated table.} -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{criteria}{function. Function which takes a \code{TableRow} object and returns -\code{TRUE} if that row should be removed. Defaults to -\code{\link{all_zero_or_na}}} +\item{criteria}{(\code{function})\cr function which takes a \code{TableRow} object and returns \code{TRUE} if that row +should be removed. Defaults to \code{\link[=all_zero_or_na]{all_zero_or_na()}}.} -\item{min}{numeric(1). (\code{low_obs_pruner} only). Minimum aggregate count value. -Subtables whose combined/average count are below this threshold will be -pruned} +\item{min}{(\code{numeric(1)})\cr (used by \code{low_obs_pruner} only). Minimum aggregate count value. +Subtables whose combined/average count are below this threshold will be pruned.} -\item{type}{character(1). How count values should be aggregated. Must be -\code{"sum"} (the default) or \code{"mean"}} +\item{type}{(\code{string})\cr how count values should be aggregated. Must be \code{"sum"} (the default) or \code{"mean"}.} } \value{ -A logical value indicating whether \code{tr} should be included -(\code{TRUE}) or pruned (\code{FALSE}) during pruning. +A logical value indicating whether \code{tr} should be included (\code{TRUE}) or pruned (\code{FALSE}) during pruning. } \description{ -Criteria functions (and constructors thereof) for trimming and pruning -tables. +Criteria functions (and constructors thereof) for trimming and pruning tables. } \details{ -\code{all_zero_or_na} returns \code{TRUE} (and thus indicates -trimming/pruning) for any \emph{non-\code{LabelRow}} \code{TableRow} which contain -only any mix of \code{NA} (including \code{NaN}), \code{0}, \code{Inf} and -\code{-Inf} values. - -\code{all_zero} returns \code{TRUE} for any non-Label row which -contains only (non-missing) zero values. - -\code{content_all_zeros_nas} Prunes a subtable if a) it has a -content table with exactly one row in it, and b) \code{all_zero_or_na} -returns \code{TRUE} for that single content row. In practice, when the -default summary/content function is used, this represents pruning any -subtable which corresponds to an empty set of the input data (e.g., because -a factor variable was used in \code{\link{split_rows_by}} but not all -levels were present in the data). - -\code{prune_empty_level} combines \code{all_zero_or_na} behavior for -\code{TableRow} objects, \code{content_all_zeros_nas} on -\code{content_table(tt)} for \code{TableTree} objects, and an additional -check that returns \code{TRUE} if the \code{tt} has no children. - -\code{prune_zeros_only} behaves as \code{prune_empty_level} does, -except that like \code{all_zero} it prunes only in the case of all -non-missing zero values. - -\code{low_obs_pruner} is a \emph{constructor function} which, when -called, returns a pruning criteria function which will prune on content -rows by comparing sum or mean (dictated by \code{type}) of the count -portions of the cell values (defined as the first value per cell regardless -of how many values per cell there are) against \code{min}. +\code{all_zero_or_na} returns \code{TRUE} (and thus indicates trimming/pruning) for any \emph{non-\code{LabelRow}} +\code{TableRow} which contain only any mix of \code{NA} (including \code{NaN}), \code{0}, \code{Inf} and \code{-Inf} values. + +\code{all_zero} returns \code{TRUE} for any non-\code{LabelRow} which contains only (non-missing) zero values. + +\code{content_all_zeros_nas} prunes a subtable if both of the following are true: +\itemize{ +\item It has a content table with exactly one row in it. +\item \code{all_zero_or_na} returns \code{TRUE} for that single content row. In practice, when the default summary/content +function is used, this represents pruning any subtable which corresponds to an empty set of the input data +(e.g. because a factor variable was used in \code{\link[=split_rows_by]{split_rows_by()}} but not all levels were present in the data). +} + +\code{prune_empty_level} combines \code{all_zero_or_na} behavior for \code{TableRow} objects, \code{content_all_zeros_nas} on +\code{content_table(tt)} for \code{TableTree} objects, and an additional check that returns \code{TRUE} if the \code{tt} has no +children. + +\code{prune_zeros_only} behaves as \code{prune_empty_level} does, except that like \code{all_zero} it prunes +only in the case of all non-missing zero values. + +\code{low_obs_pruner} is a \emph{constructor function} which, when called, returns a pruning criteria function which +will prune on content rows by comparing sum or mean (dictated by \code{type}) of the count portions of the cell +values (defined as the first value per cell regardless of how many values per cell there are) against \code{min}. } \examples{ adsl <- ex_adsl diff --git a/man/trim_rows.Rd b/man/trim_rows.Rd index 1037fe76b..d96a125d7 100644 --- a/man/trim_rows.Rd +++ b/man/trim_rows.Rd @@ -7,31 +7,26 @@ trim_rows(tt, criteria = all_zero_or_na) } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{criteria}{function. Function which takes a \code{TableRow} object and returns -\code{TRUE} if that row should be removed. Defaults to -\code{\link{all_zero_or_na}}} +\item{criteria}{(\code{function})\cr function which takes a \code{TableRow} object and returns \code{TRUE} if that row +should be removed. Defaults to \code{\link[=all_zero_or_na]{all_zero_or_na()}}.} } \value{ -The table with rows that have only NA or 0 cell values removed +The table with rows that have only \code{NA} or 0 cell values removed. } \description{ Trim rows from a populated table without regard for table structure } \details{ -This function will be deprecated in the future in favor of the more -elegant and versatile \code{\link[=prune_table]{prune_table()}} function which can perform the -same function as \code{trim_rows()} but is more powerful as it takes table -structure into account. +This function will be deprecated in the future in favor of the more elegant and versatile \code{\link[=prune_table]{prune_table()}} +function which can perform the same function as \code{trim_rows()} but is more powerful as it takes table structure +into account. } \note{ -Visible \code{LabelRow}s are including in this trimming, which can lead -to either all label rows being trimmed or label rows remaining when all -data rows have been trimmed, depending on what \code{criteria} returns when -called on a \code{LabelRow} object. To avoid this, use the -structurally-aware \code{\link{prune_table}} machinery instead. +Visible \code{LabelRow}s are including in this trimming, which can lead to either all label rows being trimmed or +label rows remaining when all data rows have been trimmed, depending on what \code{criteria} returns when called on +a \code{LabelRow} object. To avoid this, use the structurally-aware \code{\link[=prune_table]{prune_table()}} machinery instead. } \examples{ adsl <- ex_adsl diff --git a/man/trim_zero_rows.Rd b/man/trim_zero_rows.Rd deleted file mode 100644 index 013bd7e20..000000000 --- a/man/trim_zero_rows.Rd +++ /dev/null @@ -1,17 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/deprecated.R -\name{trim_zero_rows} -\alias{trim_zero_rows} -\title{Trim Zero Rows} -\usage{ -trim_zero_rows(tbl) -} -\arguments{ -\item{tbl}{table object} -} -\value{ -an \code{rtable} object -} -\description{ -Trim Zero Rows -} diff --git a/man/tsv_io.Rd b/man/tsv_io.Rd index 8149d469c..8bd4c3da8 100644 --- a/man/tsv_io.Rd +++ b/man/tsv_io.Rd @@ -3,7 +3,7 @@ \name{export_as_tsv} \alias{export_as_tsv} \alias{import_from_tsv} -\title{Create Enriched flat value table with paths} +\title{Create enriched flat value table with paths} \usage{ export_as_tsv( tt, @@ -15,35 +15,32 @@ export_as_tsv( import_from_tsv(file) } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{file}{character(1). The path of the file to written to or read from.} +\item{file}{(\code{string})\cr the path of the file to written to or read from.} -\item{path_fun}{function. Function to transform paths into single-string -row/column names.} +\item{path_fun}{(\code{function})\cr function to transform paths into single-string row/column names.} -\item{value_fun}{function. Function to transform cell values into cells of -the data.frame. Defaults to \code{collapse_values} which creates strings -where multi-valued cells are collapsed together, separated by \code{|}.} +\item{value_fun}{(\code{function})\cr function to transform cell values into cells of a \code{data.frame}. Defaults to +\code{collapse_values}, which creates strings where multi-valued cells are collapsed together, separated by \code{|}.} } \value{ -\code{NULL} silently for \code{export_as_tsv}, a data.frame with -re-constituted list values for \code{export_as_tsv}. +\itemize{ +\item \code{export_as_tsv} returns \code{NULL} silently. +\item \code{import_from_tsv} returns a \code{data.frame} with re-constituted list values. +} } \description{ -This function creates a flat tabular file of cell values and -corresponding paths via \code{\link[=path_enriched_df]{path_enriched_df()}}. I then -writes that data.frame out as a \code{tsv} file. - -By default (i.e. when \code{value_func} is not specified, -List columns where at least one value has length > 1 are collapsed -to character vectors by collapsing the list element with \code{"|"}. +This function creates a flat tabular file of cell values and corresponding paths via \code{\link[=path_enriched_df]{path_enriched_df()}}. It then +writes that data frame out as a \code{tsv} file. +} +\details{ +By default (i.e. when \code{value_func} is not specified, list columns where at least one value has length > 1 are +collapsed to character vectors by collapsing the list element with \code{"|"}. } \note{ -There is currently no round-trip capability for this type of export. -You can read values exported this way back in via \code{import_from_tsv} -but you will receive only the data.frame version back, NOT a \code{TableTree}. +There is currently no round-trip capability for this type of export. You can read values exported this way back in +via \code{import_from_tsv} but you will receive only the \code{data.frame} version back, NOT a \code{TableTree}. } \seealso{ \code{\link[=path_enriched_df]{path_enriched_df()}} for the underlying function that does the work. diff --git a/man/tt_to_flextable.Rd b/man/tt_to_flextable.Rd index db64e25fc..075e9355e 100644 --- a/man/tt_to_flextable.Rd +++ b/man/tt_to_flextable.Rd @@ -3,7 +3,7 @@ \name{tt_to_flextable} \alias{tt_to_flextable} \alias{theme_docx_default} -\title{Create a \code{FlexTable} from an \code{rtables} table} +\title{Create a \code{flextable} from an \code{rtables} table} \usage{ tt_to_flextable( tt, @@ -33,78 +33,66 @@ theme_docx_default( ) } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{theme}{function(1). Defaults to \code{theme_docx_default(tt)}. It expects a -a theme function that is designed internally as a function of a \code{flextable} object -and changes its layout and style. If set to \code{NULL}, it will produce a table similar -to \code{rtables} default.} +\item{theme}{(\code{function} or \code{NULL})\cr A theme function that is designed internally as a function of a \code{flextable} +object to change its layout and style. If \code{NULL}, it will produce a table similar to \code{rtables} default. Defaults +to \code{theme_docx_default(tt)}.} -\item{border}{\code{officer} border object. Defaults to \code{officer::fp_border(width = 0.5)}.} +\item{border}{(\code{officer} border object)\cr defaults to \code{officer::fp_border(width = 0.5)}.} -\item{indent_size}{integer(1). If \code{NULL}, the default indent size of the table (see -\code{\link[=matrix_form]{matrix_form()}} \code{indent_size}) is used. To work with \code{docx}, any size is multiplied -by 2 mm (5.67 pt) as default.} +\item{indent_size}{(\code{integer(1)})\cr if \code{NULL}, the default indent size of the table (see \code{\link[=matrix_form]{matrix_form()}} +\code{indent_size}) is used. To work with \code{docx}, any size is multiplied by 2 mm (5.67 pt) by default.} -\item{titles_as_header}{logical(1). Defaults to \code{TRUE} for \code{\link[=tt_to_flextable]{tt_to_flextable()}}, so the -table is self-contained as it makes additional header rows for \code{\link[=main_title]{main_title()}} -string and \code{\link[=subtitles]{subtitles()}} character vector (one per element). \code{FALSE} is suggested -for \code{\link[=export_as_docx]{export_as_docx()}}. This adds titles and subtitles as a text paragraph above -the table. Same style is applied.} +\item{titles_as_header}{(\code{flag})\cr defaults to \code{TRUE} for \code{\link[=tt_to_flextable]{tt_to_flextable()}}, so the table is self-contained +as it makes additional header rows for \code{\link[=main_title]{main_title()}} string and \code{\link[=subtitles]{subtitles()}} character vector (one per element). +\code{FALSE} is suggested for \code{\link[=export_as_docx]{export_as_docx()}}. This adds titles and subtitles as a text paragraph above the table. +The same style is applied.} -\item{footers_as_text}{logical(1). Defaults to \code{FALSE} for \code{\link[=tt_to_flextable]{tt_to_flextable()}}, so -the table is self-contained with the \code{flextable} definition of footnotes. \code{TRUE} is -used for \code{\link[=export_as_docx]{export_as_docx()}} to add the footers as a new paragraph after the table. -Same style is applied, but with a smaller font.} +\item{footers_as_text}{(\code{flag})\cr defaults to \code{FALSE} for \code{\link[=tt_to_flextable]{tt_to_flextable()}}, so the table is self-contained with +the \code{flextable} definition of footnotes. \code{TRUE} is used for \code{\link[=export_as_docx]{export_as_docx()}} to add the footers as a new +paragraph after the table. The same style is applied, but with a smaller font.} -\item{counts_in_newline}{logical(1). Defaults to \code{FALSE}. In \code{rtables} text printing -(\code{\link[formatters:tostring]{formatters::toString()}}), the column counts, i.e. \code{(N=xx)}, is always on a new line. -We noticed that for \code{docx} exports could be necessary to have it on the same line.} +\item{counts_in_newline}{(\code{flag})\cr defaults to \code{FALSE}. In \code{rtables} text printing (\code{\link[formatters:tostring]{formatters::toString()}}), +the column counts, i.e. \code{(N=xx)}, are always on a new line. For \code{docx} exports it could be necessary to print it +on the same line.} -\item{paginate}{logical(1). If you need \code{.docx} export and you use -\code{export_as_docx}, we suggest relying on \code{word} pagination system. Cooperation -between the two mechanisms is not guaranteed. This option splits \code{tt} in different -"pages" as multiple \code{flextables}. Defaults to \code{FALSE}.} +\item{paginate}{(\code{flag})\cr when exporting \code{.docx} documents using \code{export_as_docx}, we suggest relying on the +Microsoft Word pagination system. If \code{TRUE}, this option splits \code{tt} into different "pages" as multiple +\code{flextables}. Cooperation between the two mechanisms is not guaranteed. Defaults to \code{FALSE}.} -\item{lpp}{numeric. Maximum lines per page including (re)printed header and context rows} +\item{lpp}{(\code{numeric(1)})\cr maximum lines per page including (re)printed header and context rows.} -\item{cpp}{numeric(1) or NULL. Width (in characters) of the pages for -horizontal pagination. \code{NA} (the default) indicates \code{cpp} should be inferred from -the page size; \code{NULL} indicates no horizontal pagination should be done -regardless of page size.} +\item{cpp}{(\code{numeric(1)} or \code{NULL})\cr width (in characters) of the pages for horizontal pagination. +\code{NA} (the default) indicates \code{cpp} should be inferred from the page size; \code{NULL} indicates no horizontal +pagination should be done regardless of page size.} -\item{...}{Passed on to methods or tabulation functions.} +\item{...}{additional parameters passed to methods or tabulation functions.} -\item{colwidths}{numeric vector. Column widths for use with vertical pagination.} +\item{colwidths}{(\code{numeric})\cr a vector of column widths 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{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{total_width}{numeric(1). Total width in inches for the resulting -\code{flextable(s)}. Defaults to 10.} +\item{total_width}{(\code{numeric(1)})\cr total width (in inches) for the resulting flextable(s). Defaults to 10.} -\item{font}{character(1). Defaults to \code{"Arial"}. If the font is not available, \code{flextable} -default is used.} +\item{font}{(\code{string})\cr defaults to \code{"Arial"}. If the font is not available, \code{flextable} default is used.} -\item{font_size}{integer(1). Positive integerish value that defaults to 9.} +\item{font_size}{(\code{integer(1)})\cr font size. Defaults to 9.} -\item{bold}{character vector. It can be any combination of \code{c("header", "content_rows", "label_rows")}. The first one renders all column names bold (not \code{topleft} content). -Second and third option use \code{\link[=make_row_df]{make_row_df()}} to render content or/and label -rows as bold.} +\item{bold}{(\code{character})\cr parts of the table text that should be in bold. Can be any combination of +\code{c("header", "content_rows", "label_rows")}. The first one renders all column names bold (not \code{topleft} content). +The second and third option use \code{\link[=make_row_df]{make_row_df()}} to render content or/and label rows as bold.} -\item{bold_manual}{named list. List of indexes lists. See example for needed structure. -Accepted groupings/names are \code{c("header", "body")}.} +\item{bold_manual}{(named \code{list} or \code{NULL})\cr list of index lists. See example for needed structure. Accepted +groupings/names are \code{c("header", "body")}.} } \value{ -a \code{flextable} object. +A \code{flextable} object. } \description{ Principally used for export (\code{\link[=export_as_docx]{export_as_docx()}}), this function produces a \code{flextable} @@ -113,7 +101,7 @@ from an \code{rtables} table. If \code{theme = NULL}, \code{rtables}-like style } \section{Functions}{ \itemize{ -\item \code{theme_docx_default()}: main theme function for \code{\link[=export_as_docx]{export_as_docx()}} +\item \code{theme_docx_default()}: Main theme function for \code{\link[=export_as_docx]{export_as_docx()}} }} \examples{ diff --git a/man/ttap.Rd b/man/ttap.Rd index 399be14a7..592d5c480 100644 --- a/man/ttap.Rd +++ b/man/ttap.Rd @@ -3,29 +3,27 @@ \name{tt_at_path} \alias{tt_at_path} \alias{tt_at_path<-} -\title{Get or set table elements at specified path} +\title{Access or set table elements at specified path} \usage{ tt_at_path(tt, path, ...) tt_at_path(tt, path, ...) <- value } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} -\item{path}{character. A vector path for a position within the structure of a -\code{tabletree}. Each element represents a subsequent choice amongst the children -of the previous choice.} +\item{path}{(\code{character})\cr a vector path for a position within the structure of a \code{TableTree}. Each element +represents a subsequent choice amongst the children of the previous choice.} -\item{\dots}{unused.} +\item{...}{unused.} -\item{value}{The new value} +\item{value}{(\code{ANY})\cr the new value.} } \description{ -Get or set table elements at specified path +Access or set table elements at specified path } \note{ -Setting \code{NULL} at a defined path removes the corresponding sub table. +Setting \code{NULL} at a defined path removes the corresponding sub-table. } \examples{ # Accessing sub table. diff --git a/man/update_ref_indexing.Rd b/man/update_ref_indexing.Rd index c6628f747..a00b03c5d 100644 --- a/man/update_ref_indexing.Rd +++ b/man/update_ref_indexing.Rd @@ -2,24 +2,21 @@ % Please edit documentation in R/index_footnotes.R \name{update_ref_indexing} \alias{update_ref_indexing} -\title{Update footnote indexes on a built table} +\title{Update footnote indices on a built table} \usage{ update_ref_indexing(tt) } \arguments{ -\item{tt}{\code{TableTree} (or related class). A \code{TableTree} object representing a -populated table.} +\item{tt}{(\code{TableTree} or related class)\cr a \code{TableTree} object representing a populated table.} } \description{ -Re-indexes footnotes within a built table +Re-indexes footnotes within a built table. } \details{ -After adding or removing referential footnotes manually, -or after subsetting a table, the reference indexes (i.e. the -number associated with specific footnotes) may be incorrect. -This function recalculates these based on the full table. +After adding or removing referential footnotes manually, or after subsetting a table, the reference indexes +(i.e. the number associated with specific footnotes) may be incorrect. This function recalculates these based +on the full table. } \note{ -In the future this should not generally need to be called -manually. +In the future this should not generally need to be called manually. } diff --git a/man/validate_table_struct.Rd b/man/validate_table_struct.Rd index d2c4f7faf..3f68f8bcf 100644 --- a/man/validate_table_struct.Rd +++ b/man/validate_table_struct.Rd @@ -3,47 +3,51 @@ \name{validate_table_struct} \alias{validate_table_struct} \alias{assert_valid_table} -\title{Validate and Assert valid table structure (Experimental).} +\title{Validate and assert valid table structure} \usage{ validate_table_struct(tt) assert_valid_table(tt, warn_only = FALSE) } \arguments{ -\item{tt}{\code{TableTree} +\item{tt}{(\code{TableTree})\cr a \code{TableTree} object.} -A \code{TableTree} (\code{rtables}-built table) is considered degenerate if -\enumerate{ -\item{it contains no subtables or data rows (content rows do not count)} -\item{it contains a subtable which is degenerate by the criterion above} -} - -\code{validate_table_struct} assesses whether \code{tt} has a valid (non-degenerate) -structure. - -\code{assert_valid_table} asserts a table must have a valid structure, -and throws an informative error (the default) or warning (if \code{warn_only} -is \code{TRUE}) if the table is degenerate (has invalid structure or -contains one or more invalid substructures} - -\item{warn_only}{logical(1). Should a warning be thrown instead of an error? -Defaults to \code{FALSE}} +\item{warn_only}{(\code{flag})\cr whether a warning should be thrown instead of an error. Defaults to \code{FALSE}.} } \value{ -for \code{validate_table_struct} a logical value indicating valid structure; -\code{assert_valid_table} is called for its side-effect of throwing an error -or warning for degenerate tables. +\itemize{ +\item \code{validate_table_struct} returns a logical value indicating valid structure. +\item \code{assert_valid_table} is called for its side-effect of throwing an error or warning for degenerate tables. +} } \description{ -Validate and Assert valid table structure (Experimental). +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} + +A \code{TableTree} (\code{rtables}-built table) is considered degenerate if: +\enumerate{ +\item{It contains no subtables or data rows (content rows do not count).} +\item{It contains a subtable which is degenerate by the criterion above.} +} + +\code{validate_table_struct} assesses whether \code{tt} has a valid (non-degenerate) structure. + +\code{assert_valid_table} asserts a table must have a valid structure, and throws an informative error (the default) or +warning (if \code{warn_only} is \code{TRUE}) if the table is degenerate (has invalid structure or contains one or more +invalid substructures. } \note{ -This function is experimental and the exact text of the warning/error -is subject to change in future releases. +This function is experimental and the exact text of the warning/error is subject to change in future releases. } \examples{ validate_table_struct(rtable("hahaha")) \dontrun{ assert_valid_table(rtable("oops")) } + +} +\seealso{ +Other table structure validation functions: +\code{\link{find_degen_struct}()}, +\code{\link{sanitize_table_struct}()} } +\concept{table structure validation functions} diff --git a/man/value_formats.Rd b/man/value_formats.Rd index 0671439c5..e0cd04b80 100644 --- a/man/value_formats.Rd +++ b/man/value_formats.Rd @@ -6,7 +6,7 @@ \alias{value_formats,TableRow-method} \alias{value_formats,LabelRow-method} \alias{value_formats,VTableTree-method} -\title{Value Formats} +\title{Value formats} \usage{ value_formats(obj, default = obj_format(obj)) @@ -19,17 +19,16 @@ value_formats(obj, default = obj_format(obj)) \S4method{value_formats}{VTableTree}(obj, default = obj_format(obj)) } \arguments{ -\item{obj}{A table or row object.} +\item{obj}{(\code{VTableTree} or \code{TableRow})\cr a table or row object.} -\item{default}{\code{FormatSpec}.} +\item{default}{(\code{string}, \code{function}, or \code{list})\cr default format.} } \value{ -Matrix (storage mode list) containing the effective format for each -cell position in the table (including 'virtual' cells implied by label rows, -whose formats are always \code{NULL}). +Matrix (storage mode list) containing the effective format for each cell position in the table +(including 'virtual' cells implied by label rows, whose formats are always \code{NULL}). } \description{ -Returns a matrix of formats for the cells in a table +Returns a matrix of formats for the cells in a table. } \examples{ lyt <- basic_table() \%>\% diff --git a/man/varcuts.Rd b/man/varcuts.Rd index 4d6dfe9f9..5c15380d8 100644 --- a/man/varcuts.Rd +++ b/man/varcuts.Rd @@ -86,78 +86,65 @@ split_rows_by_cutfun( ) } \arguments{ -\item{lyt}{layout object pre-data used for tabulation} +\item{lyt}{(\code{PreDataTableLayouts})\cr layout object pre-data used for tabulation.} -\item{var}{string, variable name} +\item{var}{(\code{string})\cr variable name.} -\item{cuts}{numeric. Cuts to use} +\item{cuts}{(\code{numeric})\cr cuts to use.} -\item{cutlabels}{character (or NULL). Labels for the cuts} +\item{cutlabels}{(\code{character} or \code{NULL})\cr labels for the cuts.} -\item{split_label}{string. Label string to be associated with the table -generated by the split. Not to be confused with labels assigned to each -child (which are based on the data and type of split during tabulation).} +\item{split_label}{(\code{string})\cr label to be associated with the table generated by the split. Not to be confused +with labels assigned to each child (which are based on the data and type of split during tabulation).} -\item{nested}{boolean. Should this layout instruction be applied within the -existing layout structure \emph{if possible} (\code{TRUE}, the default) or as a -new top-level element (`FALSE). Ignored if it would nest a split underneath -analyses, which is not allowed.} +\item{nested}{(\code{logical})\cr whether this layout instruction should be applied within the existing layout structure +\emph{if possible} (\code{TRUE}, the default) or as a new top-level element (\code{FALSE}). Ignored if it would nest a split +underneath analyses, which is not allowed.} -\item{cumulative}{logical. Should the cuts be treated as cumulative. Defaults -to \code{FALSE}} +\item{cumulative}{(\code{flag})\cr whether the cuts should be treated as cumulative. Defaults to \code{FALSE}.} -\item{format}{\code{FormatSpec}. Format associated with this split. Formats can be -declared via strings (\code{"xx.x"}) or function. In cases such as -\code{analyze} calls, they can character vectors or lists of functions.} +\item{format}{(\code{string}, \code{function}, or \code{list})\cr format associated with this split. Formats can be declared via +strings (\code{"xx.x"}) or function. In cases such as \code{analyze} calls, they can be character vectors or lists of +functions. See \code{\link[formatters:list_formats]{formatters::list_valid_format_labels()}} for a list of all available format strings.} -\item{na_str}{character(1). String that should be displayed when the value of \code{x} is missing. -Defaults to \code{"NA"}.} +\item{na_str}{(\code{string})\cr string that should be displayed when the value of \code{x} is missing. Defaults to \code{"NA"}.} -\item{label_pos}{character(1). Location the variable label should be -displayed, Accepts \code{"hidden"} (default for non-analyze row splits), \code{"visible"}, -\code{"topleft"}, and - for analyze splits only - \code{"default"}. For analyze calls, -\code{"default"} indicates that the variable should be visible if and only if -multiple variables are analyzed at the same level of nesting.} +\item{label_pos}{(\code{string})\cr location where the variable label should be displayed. Accepts \code{"hidden"} +(default for non-analyze row splits), \code{"visible"}, \code{"topleft"}, and \code{"default"} (for analyze splits only). For +\code{analyze} calls, \code{"default"} indicates that the variable should be visible if and only if multiple variables are +analyzed at the same level of nesting.} -\item{section_div}{character(1). String which should be repeated as a section -divider after each group defined by this split instruction, or -\code{NA_character_} (the default) for no section divider.} +\item{section_div}{(\code{string})\cr string which should be repeated as a section divider after each group defined +by this split instruction, or \code{NA_character_} (the default) for no section divider.} -\item{cutfun}{function. Function which accepts the full vector of \code{var} -values and returns cut points to be passed to \code{cut}.} +\item{cutfun}{(\code{function})\cr function which accepts the \emph{full vector} of \code{var} values and returns cut points to be +used (via \code{cut}) when splitting data during tabulation.} -\item{cutlabelfun}{function. Function which returns either labels for the -cuts or NULL when passed the return value of \code{cutfun}} +\item{cutlabelfun}{(\code{function})\cr function which returns either labels for the cuts or \code{NULL} when passed the +return value of \code{cutfun}.} -\item{extra_args}{list. Extra arguments to be passed to the tabulation -function. Element position in the list corresponds to the children of this -split. Named elements in the child-specific lists are ignored if they do +\item{extra_args}{(\code{list})\cr extra arguments to be passed to the tabulation function. Element position in the list +corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do not match a formal argument of the tabulation function.} -\item{child_labels}{string. One of \code{"default"}, \code{"visible"}, -\code{"hidden"}. What should the display behavior be for the labels (i.e. -label rows) of the children of this split. Defaults to \code{"default"} -which flags the label row as visible only if the child has 0 content rows.} +\item{child_labels}{(\code{string})\cr the display behavior for the labels (i.e. label rows) of the children of this +split. Accepts \code{"default"}, \code{"visible"}, and \code{"hidden"}. Defaults to \code{"default"} which flags the label row as +visible only if the child has 0 content rows.} -\item{indent_mod}{numeric. Modifier for the default indent position for the -structure created by this function(subtable, content table, or row) -\emph{and all of that structure's children}. Defaults to 0, which +\item{indent_mod}{(\code{numeric})\cr modifier for the default indent position for the structure created by this +function (subtable, content table, or row) \emph{and all of that structure's children}. Defaults to 0, which corresponds to the unmodified default behavior.} } \value{ -A \code{PreDataTableLayouts} object suitable for passing to further -layouting functions, and to \code{build_table}. +A \code{PreDataTableLayouts} object suitable for passing to further layouting functions, and to \code{\link[=build_table]{build_table()}}. } \description{ -Create columns (or row splits) based on values (such as quartiles) of -\code{var}. +Create columns (or row splits) based on values (such as quartiles) of \code{var}. } \details{ -For dynamic cuts, the cut is transformed into a static cut by -\code{\link{build_table}} \emph{based on the full dataset}, before -proceeding. Thus even when nested within another split in column/row space, -the resulting split will reflect the overall values (e.g., quartiles) in the -dataset, NOT the values for subset it is nested under. +For dynamic cuts, the cut is transformed into a static cut by \code{\link[=build_table]{build_table()}} \emph{based on the full dataset}, +before proceeding. Thus even when nested within another split in column/row space, the resulting split will reflect +the overall values (e.g., quartiles) in the dataset, NOT the values for subset it is nested under. } \examples{ library(dplyr) diff --git a/man/vil.Rd b/man/vil.Rd index ec4a7e8eb..391cae8f9 100644 --- a/man/vil.Rd +++ b/man/vil.Rd @@ -8,7 +8,7 @@ \alias{vars_in_layout,Split-method} \alias{vars_in_layout,CompoundSplit-method} \alias{vars_in_layout,ManualSplit-method} -\title{List Variables required by a pre-data table layout} +\title{List variables required by a pre-data table layout} \usage{ vars_in_layout(lyt) @@ -25,34 +25,30 @@ vars_in_layout(lyt) \S4method{vars_in_layout}{ManualSplit}(lyt) } \arguments{ -\item{lyt}{The Layout (or a component thereof)} +\item{lyt}{(\code{PreDataTableLayouts})\cr the layout (or a component thereof).} } \value{ -A character vector containing the unique variables explicitly used in the layout (see Notes). +A character vector containing the unique variables explicitly used in the layout (see the notes below). } \description{ -List Variables required by a pre-data table layout +List variables required by a pre-data table layout } \details{ -This will walk the layout declaration and return a vector -of the names of the unique variables that are used in any of -the following ways: - +This will walk the layout declaration and return a vector of the names of the unique variables that are used +in any of the following ways: \itemize{ -\item{Variable being split on (directly or via cuts)} -\item{Element of a Multi-variable column split} -\item{Content variable} -\item{Value-label variable} +\item Variable being split on (directly or via cuts) +\item Element of a Multi-variable column split +\item Content variable +\item Value-label variable } } \note{ -This function will not detect dependencies implicit in -analysis or summary functions which accept \code{x} or \code{df} and then -rely on the existence of particular variables not being split on/ -analyzed. - -The order these variable names appear within the return vector -is undefined and should not be relied upon. +\itemize{ +\item This function will not detect dependencies implicit in analysis or summary functions which accept \code{x} +or \code{df} and then rely on the existence of particular variables not being split on/analyzed. +\item The order these variable names appear within the return vector is undefined and should not be relied upon. +} } \examples{ lyt <- basic_table() \%>\% diff --git a/tests/testthat/test-deprecated.R b/tests/testthat/test-deprecated.R index fd33c2c00..cbd701c8b 100644 --- a/tests/testthat/test-deprecated.R +++ b/tests/testthat/test-deprecated.R @@ -8,18 +8,14 @@ test_that("deprecated things are still there and work kinda", { expect_identical(lyt22, basic_table() %>% split_rows_by("ARM")) }) -test_that("deprecated insert_rrow and summarize_rows still currently work", { +test_that("deprecated insert_rrow still currently works", { tbl <- basic_table() %>% split_cols_by("Species") %>% analyze("Sepal.Length") %>% build_table(iris) expect_warning(res1 <- insert_rrow(tbl, rrow("Hello World")), "Deprecated") - expect_warning(resdf <- summarize_rows(tbl), "Deprecated") - row.names(resdf) <- NULL realdf <- make_row_df(tbl) - cololaps <- intersect(names(resdf), names(realdf)) - expect_true(all.equal(resdf[, cololaps], realdf[, cololaps])) o <- options(warn = -1) mf1 <- matrix_form(res1) expect_identical(mf1$strings[2, , drop = TRUE], c("Hello World", "", "", "")) @@ -34,7 +30,6 @@ test_that("deprecated insert_rrow and summarize_rows still currently work", { analyze("Sepal.Length") %>% build_table(iris) ## for coverage - expect_warning(resdf2 <- summarize_rows(tbl2), "Deprecated") res3 <- insert_rrow(tbl2, rrow("Hello World")) mf3 <- matrix_form(res3) expect_identical(mf3$strings[2, , drop = TRUE], c("Hello World", "", "", "")) diff --git a/tests/testthat/test-sort-prune.R b/tests/testthat/test-sort-prune.R index 5842de38a..bb3d3e262 100644 --- a/tests/testthat/test-sort-prune.R +++ b/tests/testthat/test-sort-prune.R @@ -133,41 +133,7 @@ test_that("sort_at_path just returns an empty input table", { expect_identical(emptytable, result) }) - -test_that("trim_zero_rows, trim_rows, prune do the same thing in normal cases", { - tbl <- basic_table() %>% - split_rows_by("RACE") %>% - analyze("COUNTRY") %>% - build_table(ex_adsl) - - expect_warning(tzr_tbl1 <- trim_zero_rows(tbl), "deprecated") - tr_tbl1 <- trim_rows(tbl) - - expect_true(all(unclass(compare_rtables(tzr_tbl1, tr_tbl1)) == ".")) - - tbl2 <- basic_table() %>% - split_cols_by("ARM") %>% - split_rows_by("RACE") %>% - analyze("COUNTRY") %>% - build_table(ex_adsl) - - expect_warning(tzr_tbl2 <- trim_zero_rows(tbl2), "deprecated") - tr_tbl2 <- trim_rows(tbl2) - - expect_true(all(unclass(compare_rtables(tzr_tbl2, tr_tbl2)) == ".")) - - tbl3 <- basic_table() %>% - split_cols_by("ARM") %>% - split_cols_by("SEX") %>% - split_rows_by("RACE") %>% - analyze("COUNTRY") %>% - build_table(ex_adsl) - - expect_warning(tzr_tbl3 <- trim_zero_rows(tbl3), "deprecated") - tr_tbl3 <- trim_rows(tbl3) - - expect_true(all(unclass(compare_rtables(tzr_tbl3, tr_tbl3)) == ".")) - +test_that("trim_rows and prune_table do the same thing in normal cases", { bigtbl <- basic_table() %>% split_rows_by("RACE") %>% split_rows_by("COUNTRY") %>% @@ -307,7 +273,6 @@ test_that("provided score functions throw informative errors when invalid and * "occurred at path: AEBODSYS -> * (cl A.1)", fixed = TRUE ) - }) test_that("paths come out correct when sorting with '*'", {