diff --git a/NEWS.md b/NEWS.md index 1fecb663f..c1c768f46 100644 --- a/NEWS.md +++ b/NEWS.md @@ -8,29 +8,29 @@ ## rtables 0.6.6 ### New Features * Removed `ref_group` reordering in column splits so not to change the order. - * Added `bold` argument to `as_html` to bold specified elements, and `header_sep_line` + * Added `bold` argument to `as_html` to bold specified elements, and `header_sep_line` argument to print a horizontal line under the table header in rendered HTML output. * Duplicate referential footnotes are consolidated when tables are rendered. * Section divisors can be set for analysis rows. * Added setter and getter for section dividers (`section_div` and `section_div<-`). They also accept split section structure assignment. - * Added `header_section_div` setters and getters for layout and table objects along with + * Added `header_section_div` setters and getters for layout and table objects along with related `basic_table` parameter. * Added `na_str` argument to `analyze_colvars` to set custom string to print in place of missing values. - * Added flat `data.frame` outputs for `as_result_df()` via flag parameters `as_viewer`, `as_strings`, and + * Added flat `data.frame` outputs for `as_result_df()` via flag parameters `as_viewer`, `as_strings`, and `expand_colnames`. - * Migrated `export_as_pdf` function to `formatters`. - + * Migrated `export_as_pdf` function to `formatters`. + ### Bug Fixes * Fixed a bug that was failing when wrapping and section dividers were used at the same time. * Fixed a bug in `as_result_df` causing misalignment of column names. - * Fixed a bug that was not allowing path indexing as `row_paths()` was giving a different path due to it being made of + * Fixed a bug that was not allowing path indexing as `row_paths()` was giving a different path due to it being made of named values. * Fixed a bug in `as_result_df` when called on tables with less than 3 rows. ### Miscellaneous * Applied `styler` and resolved package lint. Changed default indentation from 4 spaces to 2. - * Added Developer Guide to pkgdown site with Debugging, Split Machinery, and Tabulation sections. + * Added Developer Guide with Debugging, Split Machinery, and Tabulation sections. * Whitespace is not trimmed when rendering tables with `as_html`. * Started deprecation cycle for `col_fnotes_here` to be replaced with `col_footnotes`. * Exported `section_div` methods now have a dedicated documentation page that is visible to users. @@ -77,7 +77,7 @@ * Removed superfluous warning which arose for custom split functions when reference group is is set (https://github.com/insightsengineering/rtables/issues/707#issuecomment-1678810598). * Fixed `qtable` labeling via `row_labels` ([#698](https://github.com/insightsengineering/rtables/issues/698)). * Error catching and test coverage for cases where `alt_counts_df` presents different splits from `df`. - + ### Miscellaneous * Cleaned up spelling in documentation ([#685](https://github.com/insightsengineering/rtables/issues/685)) * Custom appearance vignette updated with decimal alignment support. @@ -94,16 +94,16 @@ ## rtables 0.6.1 * Improved resilience of pagination machinery (`paginate_table`) by generalizing parameters' defaults (`cpp`, `lpp`, and `font_size`). - * Moved `export_as_txt` to `formatters`. Added to reexports. + * Moved `export_as_txt` to `formatters`. Added to reexports. * Migrated `export_as_rtf` to `formatters`. Not re-exported. * add `r2rtf` to Suggests * pagination logic has been migrated completely (excepting page_by splits) to `formatters` and is now invoked from there. paginate_table remains as a convenience function. - * Removed warning in `str` method when called upon table objects. - * Provide `str` method for `VTableTree` objects with a default `max.level` of 3, as the infinite default from base is not + * Removed warning in `str` method when called upon table objects. + * Provide `str` method for `VTableTree` objects with a default `max.level` of 3, as the infinite default from base is not useful or informative. * default `font_size` value is now `8` across pagination and export machinery * `margins` argument in pagination and export machinery now (correctly) interpreted as inches. This change is inherited from `formatters` - * `lpp` and `cpp` now default to `NA_integer_`, which is interpreted as inferring their value from the physical page size specified. + * `lpp` and `cpp` now default to `NA_integer_`, which is interpreted as inferring their value from the physical page size specified. * Horizontal pagination now occurs by default due to the above (because there is a default page type - `"letter"`. Pagination can still be turned off in either direction by setting `l/cpp` to `NULL` explicitly. * Referential footnotes now have both a `symbol` and an `index`. Messages associated with symbols will only appear once per page in the footer materials regardless of number of elements referenced in the page with that symbol. Matches and inherits from changes in `formatters` * Started deprecation cycle for `trim_zero_rows`. @@ -138,7 +138,7 @@ * `export_to_txt` now automatically paginates when any form of page dimension is provided (previously the default was unconditionally not paginating). * Versioned dependency on `formatters` increased to `>=0.4.0` - + ## rtables 0.5.3 * `[<-` now treats character `i` and `j` values as paths, the same as `[` always has. * `[<-` `CellValue` method now preserves `CellValue` attributes (e.g., format) @@ -153,7 +153,7 @@ * export functions now accepts `tf_wrap` and `max_width` and use them in both pagination (when turned on) *and* `toString` when used (pdf, txt exporters). * versioned dependency on `formatters` increased to `>0.3.3.10` * `export_as_pdf` now accepts standard page/font size parameters - * original parameters (`width`, `height`, `fontsize` are soft deprecated (no warning) and + * original parameters (`width`, `height`, `fontsize` are soft deprecated (no warning) and will be fully deprecated and then removed in the future. * `toString` method for `VTableTree` now accepts `tf_wrap` and `max_width` * `export_as_txt` and `export_as_pdf` now accept `cpp`, as well as `tf_wrap` and `max_width` and @@ -182,7 +182,7 @@ * Updated versioned dependency on `formatters` to `>=0.3.2.3` * Equivalent split functions with different enclosing environments (e.g., 2 identical calls to `add_combo_levels` [#340](https://github.com/insightsengineering/rtables/issues/304)) no longer block `rbind`ing * Fixed various documentation bugs where description section was being added to header. - + ## rtables 0.5.1.4 * empty level check for splitting variables reinstated. @@ -196,7 +196,7 @@ * `col_counts` getter and setter now accept `path` argument. * empty levels of a splitting variable now result in an informative error message (character and factor cases). * fixed bug in handling of column extra arguments that was preventing `cbind`ing tables from working correctly ([#324]](https://github.com/insightsengineering/rtables/issues/324)) - + ## rtables 0.5.1 * empty factor levels are now *not* dropped for column splits when ref_group is set ([#323](https://github.com/insightsengineering/rtables/issues/323)) * `linesep` argument to `toString` and related functions renamed to `hsep` @@ -205,15 +205,15 @@ * New `hsep` argument to `build_table` which sets the horizontal separator for the constructed table (and subtables thereof) * New `horizontal_sep` and `horizontal_sep<-` accessors for constructed tables, the latter of which is mandatorily recursive. * `split_rows_by(var, child_labels="hidden")` no longer removes the structural subtable corresponding to levels of `var` ([#314](https://github.com/insightsengineering/rtables/issues/314)) - + ## rtables 0.5.0 * `formatable` dependency renamed to `formatters` for suitability of release to CRAN - * Update versioned dependency of `formatters` (previously `formatable`) to `>=0.2.0` - + * Update versioned dependency of `formatters` (previously `formatable`) to `>=0.2.0` + ## rtables 0.4.1.0004 * Fix bug when function format combined with NULL `cfun` caused error ([#307](https://github.com/insightsengineering/rtables/issues/307)) * Fix bug in `path_enriched_df` (which powers `tsv` export), related to ([#308](https://github.com/insightsengineering/rtables/issues/308)) - + ## rtables 0.4.1.0002 * added `table_shell` to display shell of table with formats @@ -231,14 +231,14 @@ * new `tt_to_flextable` coercion function * new `export_as_pdf` exporter function * `value_at` and `cell_values` functions now have methods for `TableRow` objects making them usable in sorting/pruning functions - + ## rtables 0.3.8.9001 * new `trim_levels_to_map` split function based on `[@wwojciech](https://github.com/wwojciech)`'s work in [#203](https://github.com/insightsengineering/rtables/issues/203) * support for column referential footnotes * support for adding footnotes to existing table via `fnotes_at_path<-` function * `trim_levels_in_group` now trims empty levels of outer (split) variable by default * `value_at` and `cell_values` now work for `tablerow` objects - * Fixed `as_html` bug in `multivar` split columns case + * Fixed `as_html` bug in `multivar` split columns case * Fixed pagination off-by-one error @@ -314,8 +314,8 @@ tables in the context of clinical trials. ## rtables 0.3.2.17.9041 -* Allow single variable to be used within `split_cols_by_multivar` -* Various removal of defunct +* Allow single variable to be used within `split_cols_by_multivar` +* Various removal of defunct ## rtables 0.3.2.17.9040 @@ -361,7 +361,7 @@ tables in the context of clinical trials. ## rtables 0.3.2.17.9027 -* issues with no news: +* issues with no news: ## rtables 0.1.7 @@ -384,7 +384,7 @@ tables in the context of clinical trials. * `col_by` in `rtabulate` now accepts matrices: - `col_by_to_matrix`, `col_by_to_factor`, `by_factor_to_matrix`. - `by_add_total`, `by_all`, `by_combine`, `by_quartile`, `by_compare_subset`, `by_hierarchical`, `by_drop_empty_cols`. - + * New utility functions to deal with variable labels: - `label`, `var_labels<-`, `var_labels`, `var_labels_remove`, `var_relabel`, `with_label`. diff --git a/R/tt_compatibility.R b/R/tt_compatibility.R index cfee036af..15520dff7 100644 --- a/R/tt_compatibility.R +++ b/R/tt_compatibility.R @@ -476,7 +476,7 @@ rbindl_rtables <- function(x, gap = 0, check_headers = TRUE) { #' @param \dots ANY. Elements to be stacked. #' #' @note -#' When objects are rbinded, titles and footer information is retained from the first object (if any exists) if all +#' When objects are row-binded, titles and footer information is retained from the first object (if any exists) if all #' other objects have no titles/footers or have identical titles/footers. Otherwise, all titles/footers are removed #' and must be set for the bound table via the [main_title()], [subtitles()], [main_footer()], and [prov_footer()] #' functions. diff --git a/R/tt_export.R b/R/tt_export.R index 79c8b6454..cb2e3171c 100644 --- a/R/tt_export.R +++ b/R/tt_export.R @@ -75,7 +75,7 @@ formatters::export_as_txt #' Generate a Result Data Frame #' #' @description -#' Collection of utilities to exctract `data.frame` from `TableTree` objects. +#' Collection of utilities to extract `data.frame` from `TableTree` objects. #' #' @inheritParams gen_args #' @param spec character(1). The specification to use to diff --git a/inst/WORDLIST b/inst/WORDLIST index 3bcd1ce38..9eae1ae1d 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -1,5 +1,6 @@ amongst Arg +binded Carreras charset Chohan @@ -12,7 +13,7 @@ dplyr emph facetted facetting -flextable +FFFL formatter getter getters @@ -21,7 +22,9 @@ Heng ing initializer integerish +iteratively Kelkhoff +labelled Layouting layouting Lewandowski @@ -34,6 +37,7 @@ orderable Paszty pathing Phuse +postfix Postprocessing postprocessing Pre @@ -56,6 +60,7 @@ Saibah sortable spl Stoilova +STUDYID Subtable subtable subtable's @@ -65,6 +70,8 @@ summarization tableone TableTree Tadeusz +todo +unaggregated unicode univariable unnested diff --git a/man/data.frame_export.Rd b/man/data.frame_export.Rd index 97d0011aa..472a8f14a 100644 --- a/man/data.frame_export.Rd +++ b/man/data.frame_export.Rd @@ -52,7 +52,7 @@ where multi-valued cells are collapsed together, separated by \code{|}.} (processed by by \code{path_fun}). } \description{ -Collection of utilities to exctract \code{data.frame} from \code{TableTree} objects. +Collection of utilities to extract \code{data.frame} from \code{TableTree} objects. } \details{ \code{as_result_df()}: Result data frame specifications may differ in the exact information diff --git a/man/rbind.Rd b/man/rbind.Rd index 04dc8ca64..46583d2d1 100644 --- a/man/rbind.Rd +++ b/man/rbind.Rd @@ -33,7 +33,7 @@ A formal table object. \code{rbind} \code{TableTree} and related objects } \note{ -When objects are rbinded, titles and footer information is retained from the first object (if any exists) if all +When objects are row-binded, titles and footer information is retained from the first object (if any exists) if all other objects have no titles/footers or have identical titles/footers. Otherwise, all titles/footers are removed and must be set for the bound table via the \code{\link[=main_title]{main_title()}}, \code{\link[=subtitles]{subtitles()}}, \code{\link[=main_footer]{main_footer()}}, and \code{\link[=prov_footer]{prov_footer()}} functions. diff --git a/vignettes/custom_appearance.Rmd b/vignettes/custom_appearance.Rmd index 5dd0414de..1b873ba3f 100644 --- a/vignettes/custom_appearance.Rmd +++ b/vignettes/custom_appearance.Rmd @@ -7,7 +7,7 @@ vignette: > %\VignetteIndexEntry{Customizing Appearance} %\VignetteEncoding{UTF-8} %\VignetteEngine{knitr::rmarkdown} -editor_options: +editor_options: chunk_output_type: console --- @@ -40,10 +40,10 @@ It is possible to align the content by assigning `"left"`, `"center"` `in_rows()` and `rcell()`, respectively. It is also possible to use `decimal`, `dec_right`, and `dec_left` for decimal alignments. The first takes all numerical values and aligns the decimal character `.` in every value of the column that has -`align = "decimal"`. Also numberic without decimal values are aligned according to +`align = "decimal"`. Also numeric without decimal values are aligned according to an imaginary `.` if specified as such. `dec_left` and `dec_right` behave similarly, with the difference that if the column present empty spaces at left or right, it -pushes values towards left or right taking the one value that has most decimal +pushes values towards left or right taking the one value that has most decimal characters, if right, or non-decimal values if left. For more details, please read the related documentation page `help("decimal_align")`. @@ -192,7 +192,7 @@ build_table(lyt, DM) Using the post-processing function: -Without inset - +Without inset - ```{r} lyt <- basic_table() %>% analyze("AGE") @@ -201,7 +201,7 @@ tbl <- build_table(lyt, DM) tbl ``` -With an inset of 5 characters - +With an inset of 5 characters - ```{r} table_inset(tbl) <- 5 @@ -234,7 +234,7 @@ result <- build_table(lyt, ex_adsl) result ``` -With inset - +With inset - Notice, the inset does not apply to any title materials (main title, subtitles, page titles), or provenance footer @@ -353,7 +353,7 @@ basic_table( build_table(DM) ``` -Modified indent - +Modified indent - ```{r} basic_table( title = "Study XXXXXXXX", @@ -417,7 +417,7 @@ Label order will mirror the order of `split_rows_by` calls. If the labels of any subgroups should be hidden, the `label_pos` argument should be set to hidden. -"SEX" label position is hidden - +"SEX" label position is hidden - ```{r} basic_table( title = "Study XXXXXXXX", @@ -432,7 +432,7 @@ basic_table( build_table(DM) ``` -"SEX" label position is with the top-left materials - +"SEX" label position is with the top-left materials - ```{r} basic_table( diff --git a/vignettes/dev-guide/dg_debug_rtables.Rmd b/vignettes/dev-guide/dg_debug_rtables.Rmd index 7e1ec5374..8cde7814f 100644 --- a/vignettes/dev-guide/dg_debug_rtables.Rmd +++ b/vignettes/dev-guide/dg_debug_rtables.Rmd @@ -52,9 +52,9 @@ as you did recover. `<<-` for `recover` or `debugger` gives it to the global environment -#### lo-fi debugging +#### debugging techniques -* PRINT / CAT is always a low level debugging that can be used. It is helpful for server jobs where maybe only terminal or console output is available and no `browser()` can be used. For example, you can print the position or state of a function at a certain point untill you find the break point. +* PRINT / CAT is always a low level debugging that can be used. It is helpful for server jobs where maybe only terminal or console output is available and no `browser()` can be used. For example, you can print the position or state of a function at a certain point until you find the break point. * comment blocks -> does not work with pipes (you can use `identity()` it is a step that does nothing but does not break the pipes) * `browser()` bombing diff --git a/vignettes/dev-guide/dg_notes.Rmd b/vignettes/dev-guide/dg_notes.Rmd index 4afc292fc..73079c9f1 100644 --- a/vignettes/dev-guide/dg_notes.Rmd +++ b/vignettes/dev-guide/dg_notes.Rmd @@ -18,12 +18,12 @@ knitr::opts_chunk$set(echo = TRUE) ## Disclaimer -This is a collection of notes divided by issues and it is a working document that will end up being a dev vignette one day. +This is a collection of notes divided by issues and it is a working document that will end up being a developer vignette one day. ## `section_div` notes -Everything in the layout is built over split objects, that reside in `00_tabletrees.R`. There `section_div` is defined internally in each split object as `child_section_div` and assigned to `NA_character` as default. This needs to be in all split objects that need to have a separator divisor. Object-wise, the virtual class `Split` contains `section_div` and it has the following subclasses. I tagged with "X" constructor that allows for `section_div` to be assigned to a value different than `NA_character`, and "NX" otherwise. +Everything in the layout is built over split objects, that reside in `00_tabletrees.R`. There `section_div` is defined internally in each split object as `child_section_div` and assigned to `NA_character` as default. This needs to be in all split objects that need to have a separator divisor. Object-wise, the virtual class `Split` contains `section_div` and it has the following sub-classes. I tagged with "X" constructor that allows for `section_div` to be assigned to a value different than `NA_character`, and `"NX"` otherwise. ```{r} library(rtables) @@ -146,4 +146,4 @@ setMethod("section_div<-", "VTableTree", function(obj, value, only_sep_sections }) ``` -`only_sep_sections` is a parameter that is used to change only the separators (between splits) and not the data rows. It is happening forcefully if set to `TRUE`, but it is automatically activated when `section_div(tbl) <- char_v` is a character vector of length `< nrow(tbl)`. Notice that the exception for `ContentRow` is activated by the switcher `is_content_table`. This is because content rows do not have visible label row. You see that in the main table structure change we have two blocks depending on `only_sep_sections`. If `TRUE` only the `VTableTree` are modified leading to only split section separators to be modified. Also consider looking at `section_div` getter and tests in `test-accessors.R` to have more insights on the structure. Also to understand exactly how this is bound to output, please check the result of `make_row_df()` for the column `trailing_sep`. Indeed, an alternative and iterative method is used by `make_row_df` to retrieve the information about the separators for each table row. Being it a trailing separator by definition, we added `header_section_div` as a function and a parameter of `basic_table`, so to possibly add an empty line after the header (e.g. `header_section_div(tbl) = " "`). This is not a trailing separator, but it is a separator that is added after the header. To close the circle, please check how `trailing_sep` and `header_section_div` is propagated and printed/used in `formatters::toString`. +`only_sep_sections` is a parameter that is used to change only the separators (between splits) and not the data rows. It is happening forcefully if set to `TRUE`, but it is automatically activated when `section_div(tbl) <- char_v` is a character vector of length `< nrow(tbl)`. Notice that the exception for `ContentRow` is activated by the switcher `is_content_table`. This is because content rows do not have visible label row. You see that in the main table structure change we have two blocks depending on `only_sep_sections`. If `TRUE` only the `VTableTree` are modified leading to only split section separators to be modified. Also consider looking at `section_div` getter and tests in `test-accessors.R` to have more insights on the structure. Also to understand exactly how this is bound to output, please check the result of `make_row_df()` for the column `trailing_sep`. Indeed, an alternative and iterative method is used by `make_row_df` to retrieve the information about the separators for each table row. Being it a trailing separator by definition, we added `header_section_div` as a function and a parameter of `basic_table`, so to possibly add an empty line after the header (e.g. `header_section_div(tbl) = " "`). This is not a trailing separator, but it is a separator that is added after the header. To close the circle, please check how `trailing_sep` and `header_section_div` is propagated and printed/used in `formatters::toString`. diff --git a/vignettes/dev-guide/dg_split_machinery.Rmd b/vignettes/dev-guide/dg_split_machinery.Rmd index 911c57c86..b6f984587 100644 --- a/vignettes/dev-guide/dg_split_machinery.Rmd +++ b/vignettes/dev-guide/dg_split_machinery.Rmd @@ -989,4 +989,4 @@ prune_table(tbl) # (xxx) what is going on here? it is degenerate so it has no re # table tree ``` -(xxx) add the pre-proc with z-scoring +(xxx) add the pre-processing with z-scoring diff --git a/vignettes/dev-guide/dg_table_hierarchy.Rmd b/vignettes/dev-guide/dg_table_hierarchy.Rmd index c52be0fc8..0232f3861 100644 --- a/vignettes/dev-guide/dg_table_hierarchy.Rmd +++ b/vignettes/dev-guide/dg_table_hierarchy.Rmd @@ -3,7 +3,7 @@ title: "Table Hierarchy" author: "Abinaya Yogasekaram" date: "`r Sys.Date()`" output: html_document -editor_options: +editor_options: chunk_output_type: console --- @@ -21,27 +21,27 @@ Please keep in mind that `rtables` is still under active development, and it has ## Introduction -The scope of this vignette is to understand the structure of rtable objects, class hierarchy with an exploration of tree structures as S4 objects. Exploring table structure enables a better understanding of rtables concepts such as split machinery, tabulation, pagination and export. More details from the user's perspective of table structure can be found in the relevant vignettes. +The scope of this vignette is to understand the structure of `rtable` objects, class hierarchy with an exploration of tree structures as S4 objects. Exploring table structure enables a better understanding of `rtables` concepts such as split machinery, tabulation, pagination and export. More details from the user's perspective of table structure can be found in the relevant vignettes. -isS4 -getclass - for class structure +`isS4` +`getclass` - for class structure ## Process and Methods -We invite developers to use the provided examples to interactively explore the rtables hierarchy. The most helpful command is 'getClass' for a list of the slots associated with a class, in addition to related classes and their relative distances. +We invite developers to use the provided examples to interactively explore the `rtables` hierarchy. The most helpful command is `getClass` for a list of the slots associated with a class, in addition to related classes and their relative distances. ## Representation of Information before generation ## Table Representation -"PredataAxisLayout" class is used to define the data subset instructions for tabulation. 2 subclasses (one for each axis): PredataColLayout, PredataRowLayout +`PredataAxisLayout` class is used to define the data subset instructions for tabulation. 2 sub-classes (one for each axis): `PredataColLayout`, `PredataRowLayout` ## Slots, Parent-Child Relationships ## Content (summary row groups) -Splits are core functionality for rtables as tabulation and calculations are often required on subsets of the data. +Splits are core functionality for `rtables` as tabulation and calculations are often required on subsets of the data. ## Split Machinery ```{r, message=FALSE} @@ -49,25 +49,25 @@ library(rtables) getClass("TreePos") ``` -"TreePos" class contains split information as a list of the splits, split label values, and the subsets of the data that are generated by the split. +`TreePos` class contains split information as a list of the splits, split label values, and the subsets of the data that are generated by the split. -AllSplit -RootSplit -MultiVarSplit -VarStaticCutSplit -CumulativeCutSplit -VarDynCutSplit -CompoundSplit -VarLevWBaselineSplit +`AllSplit` +`RootSplit` +`MultiVarSplit` +`VarStaticCutSplit` +`CumulativeCutSplit` +`VarDynCutSplit` +`CompoundSplit` +`VarLevWBaselineSplit` -The highest level of the table hierarchy belong to "TableTree". The code below identifies the slots associated with with this class. +The highest level of the table hierarchy belong to `TableTree`. The code below identifies the slots associated with with this class. ```{r} getClass("TableTree") ``` -As an S4 object, the slots can be accessed using "@" (similar to the use of "$" for list objects). -You'll notice there are classes that fall under "Extends". The classes contained here have a relationship to the TableTree object and are "virtual" classes. To avoid the repetition of slots and carrying the same data (set of slots for example) that multiple classes may need, rtables extensively uses virtual classes. A virtual class cannot be instantiated, the purpose is for other classes to inherit information from it. +As an S4 object, the slots can be accessed using `@` (similar to the use of `$` for list objects). +You'll notice there are classes that fall under "Extends". The classes contained here have a relationship to the `TableTree` object and are "virtual" classes. To avoid the repetition of slots and carrying the same data (set of slots for example) that multiple classes may need, `rtables` extensively uses virtual classes. A virtual class cannot be instantiated, the purpose is for other classes to inherit information from it. ```{r} @@ -82,12 +82,12 @@ tt <- build_table(lyt, DM) str(tt, max.level = 2) ``` -## Tree Paths +## Tree Paths -Root to Leaves, are vectors of vectors +Root to Leaves, are vectors of vectors Tables are tree, nodes in the tree can have summaries associated with them. Tables are trees because of the nested structure. There is also the benefit of keeping and repeating necessary information when trying to paginate a table. -Children of ElementaryTables are row objects. TableTree can have children that are either row objects or other table objects. +Children of `ElementaryTables` are row objects. `TableTree` can have children that are either row objects or other table objects. #### TODO: diff --git a/vignettes/dev-guide/dg_tabulation.Rmd b/vignettes/dev-guide/dg_tabulation.Rmd index dde11bdcd..ebc08283f 100644 --- a/vignettes/dev-guide/dg_tabulation.Rmd +++ b/vignettes/dev-guide/dg_tabulation.Rmd @@ -104,7 +104,7 @@ cexprs <- make_col_subsets(ctree, df) # extracts expressions in a compact fashio colextras <- col_extra_args(ctree) # retrieves extra_args from the tree. It may not be used ``` -Next in the function is the determination of the column counts. Currently, this happens only at the leaf level, but it can certainly be calculated independently for all levels (this is an open issue in `rtables`, i.e. how to print other levels' totals). Precedence for column counts may be not documented (xxx todo). The main use case is when you are analyzing a participation-level dataset, with multiple records per subject, and you would like to retain the total numbers of subjects per column, often taken from a subject-level dataset, to use as column counts. Originally, counts were only able to be added as a vector, but it is often the case that users would like the possibility to use `alt_counts_df`. The `cinfo` object (`InstantiatedColumnInfo`) is created with all the above information. +Next in the function is the determination of the column counts. Currently, this happens only at the leaf level, but it can certainly be calculated independently for all levels (this is an open issue in `rtables`, i.e. how to print other levels' totals). Precedence for column counts may be not documented ("xxx todo"). The main use case is when you are analyzing a participation-level dataset, with multiple records per subject, and you would like to retain the total numbers of subjects per column, often taken from a subject-level dataset, to use as column counts. Originally, counts were only able to be added as a vector, but it is often the case that users would like the possibility to use `alt_counts_df`. The `cinfo` object (`InstantiatedColumnInfo`) is created with all the above information. If we continue inside `build_table`, we see `.make_ctab` used to make a root split. This is a general procedure that generates the initial root split as a content row. `ctab` is applied to this content row, which is a row that contains only a label. From `?summarize_row_groups`, you know that this is how `rtables` defines label rows, i.e. as content rows. `.make_ctab` is very similar to the function that actual creates the table rows, `.make_tablerows`. Note that this function uses `parent_cfun` and `.make_caller` to retrieve the content function inserted in above levels. Here we split the structural handling of the table object and the row-creation engine, which are divided by a `.make_tablerows` call. If you search the package, you will find that this function is only called twice, once in `.make_ctab` and once in `.make_analyzed_tab`. These two are the final elements of the table construction: the creation of rows. diff --git a/vignettes/exploratory_analysis.Rmd b/vignettes/exploratory_analysis.Rmd index 40809d487..b4f792b92 100644 --- a/vignettes/exploratory_analysis.Rmd +++ b/vignettes/exploratory_analysis.Rmd @@ -7,7 +7,7 @@ vignette: > %\VignetteIndexEntry{Exploratory Analysis} %\VignetteEncoding{UTF-8} %\VignetteEngine{knitr::rmarkdown} -editor_options: +editor_options: chunk_output_type: console --- @@ -49,7 +49,7 @@ table(ex_adsl$SEX, ex_adsl$ARM) We can easily recreate the cross-tables above with `qtable()` by specifying a data.frame with variable(s) to tabulate. The `col_vars` and `row_vars` arguments control how to split the data across columns and rows -respectively. +respectively. ```{r} qtable(ex_adsl, col_vars = "ARM") @@ -64,8 +64,8 @@ will add (N=xx) in the table header by default. This can be removed with qtable(ex_adsl, "ARM", show_colcounts = FALSE) ``` -Any variables used as the row or column facets should not have any empty -strings (""). This is because non empty values are required as labels when +Any variables used as the row or column facets should not have any empty +strings (""). This is because non empty values are required as labels when generating the table. The code below will generate an error. ```{r, eval = FALSE} @@ -120,7 +120,7 @@ ftable(t1, row.vars = c("SEX", "STRATA1")) So far in all the examples we have seen, we used counts to summarize the data in each table cell as this is the default analysis used by `qtable()`. Internally, a single analysis variable specified by `avar` is used -to generate the counts in the table. The default analysis variable is the first +to generate the counts in the table. The default analysis variable is the first variable in `data`. In the case of `ex_adsl` this is "STUDYID". Let's see what happens when we introduce some `NA` values into the @@ -134,13 +134,13 @@ qtable(tmp_adsl, row_vars = "ARM", col_vars = "SEX") ``` The resulting table is showing 0's across all cells because all the values of -the analysis variable are `NA`. +the analysis variable are `NA`. -Keep this behavior in mind when doing quick exploratory analysis using the -default counts aggregate function of `qtable`. +Keep this behavior in mind when doing quick exploratory analysis using the +default counts aggregate function of `qtable`. -If this does not suit your purpose, you can either pre-process your data to -recode the `NA` values or use another analysis function. We will see how +If this does not suit your purpose, you can either pre-process your data to +re-code the `NA` values or use another analysis function. We will see how the latter is done in the [Custom Aggregation] section. ```{r} @@ -150,7 +150,7 @@ tmp_adsl[[1]] <- addNA(tmp_adsl[[1]]) qtable(tmp_adsl, row_vars = "ARM", col_vars = "SEX") ``` -In addition, row and column variables should have `NA` levels explicitly +In addition, row and column variables should have `NA` levels explicitly labelled as above. If this is not done, the columns and/or rows will not reflect the full data. ```{r} diff --git a/vignettes/introduction.Rmd b/vignettes/introduction.Rmd index 05edf959f..d5d11712b 100644 --- a/vignettes/introduction.Rmd +++ b/vignettes/introduction.Rmd @@ -23,12 +23,12 @@ have their origin in studying tables that are commonly used to report analyses from clinical trials; however, we were careful to keep `rtables` a general purpose toolkit. -In this vignette, we give a short introduction into `rtables` and +In this vignette, we give a short introduction into `rtables` and tabulating a table. The content in this vignette is based on the following two resources: -* The [`rtables` useR 2020 presentation](https://www.youtube.com/watch?v=CBQzZ8ZhXLA) +* The [`rtables` useR 2020 presentation](https://www.youtube.com/watch?v=CBQzZ8ZhXLA) by Gabriel Becker * [`rtables` - A Framework For Creating Complex Structured Reporting Tables Via Multi-Level Faceted Computations](https://arxiv.org/pdf/2306.16610.pdf). @@ -42,13 +42,13 @@ library(dplyr) ## Overview -To build a table using `rtables` two components are required: A layout constructed +To build a table using `rtables` two components are required: A layout constructed using `rtables` functions, and a `data.frame` of unaggregated data. These two elements are combined to build a table object. Table objects contain information about both the content and the structure of the table, as well as instructions on -how this information should be processed to construct the table. After obtaining the -table object, a formatted table can be printed in ASCII format, or exported to a -variety of other formats (.txt, .pdf, .docx, etc.). +how this information should be processed to construct the table. After obtaining the +table object, a formatted table can be printed in ASCII format, or exported to a +variety of other formats (`.txt`, `.pdf`, `.docx`, etc.). ```{r echo=FALSE, fig.align='center'} knitr::include_graphics("../man/figures/rtables-basics.png") @@ -366,16 +366,16 @@ There are a number of reasons to choose `rtables` (yet another tables R package) * Path based access to cell content which is useful for automated content generation. -More in depth comparisons of the various tabulation frameworks can be found in the +More in depth comparisons of the various tabulation frameworks can be found in the [Overview of table R packages](https://rconsortium.github.io/rtrs-wg/tablepkgs.html#tablepkgs) -chapter of the Tables in Clinical Trials with R book compiled by the R Consortium +chapter of the Tables in Clinical Trials with R book compiled by the R Consortium Tables Working Group. ## Summary In this vignette you have learned: -* Every cell has an associated subset of data - this means that much of tabulation +* Every cell has an associated subset of data - this means that much of tabulation has to do with splitting/subsetting data. * Tables can be described with pre-data using layouts. * Tables are a form of visualization of data.