In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
Examples of behavior that contributes to creating a positive environment include:
Examples of unacceptable behavior by participants include:
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at support@github.com. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project’s leadership.
This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq
We welcome contributions big and small to the ongoing development of the {rtables} package. For most, the best way to contribute to the package is by filing issues for feature requests or bugs that you have encountered. For those who are interested in contributing code to the package, contributions can be made by working on current issues and opening pull requests with code changes. Any help that you are able to provide is greatly appreciated!
Contributions to this project are released to the public under the project’s open source license.
Issues are used to establish a prioritized timeline and track development progress within the package. If there is a new feature that you feel would be enhance the experience of package users, please open a Feature Request issue. If you notice a bug in the existing code, please file a Bug Fix issue with a description of the bug and a reprex (reproducible example). Other types of issues (questions, typos you’ve noticed, improvements to documentation, etc.) can be filed as well. Click here to file a new issue, and here to see the list of current issues. Please utilize labels wherever possible when creating issues for organization purposes and to narrow down the scope of the work required.
Development of the {rtables} package relies on an Issue → Branch → PR → Code Review → Merge pipeline facilitated through GitHub. If you are a more experienced programmer interested in contributing to the package code, please begin by filing an issue describing the changes you would like to make. It may be the case that your idea has already been implemented in some way, and the package maintainers can help to determine whether the feature is necessary before you begin development. Whether you are opening an issue or a pull request, the more detailed your description, the easier it will be for package maintainers to help you! To make code changes in the package, please follow the following process.
The {rtables} package is part of the NEST project and utilizes staged.dependencies to ensure to simplify the development process and track upstream and downstream package dependencies. We highly recommend installing and using this package when developing within {rtables}.
In order to work on a new pull request, please first create a branch off of main upon which you can work and commit changes. To comply with staged.dependencies standards, {rtables} uses the following branch naming convention:
main
staged.dependencies
issue#_description_of_issue@target_merge_branch
For example, 443_refactor_splits@main. In most cases, the target merge branch is the base (main) branch.
443_refactor_splits@main
Work within the {rtables} package to apply your code changes. Avoid combining issues on a single branch - ideally, each branch should be associated with a single issue and be prefixed by the issue number.
For information on the basics of the {rtables} package, please read the package vignettes, which are available here.
For advanced development work within {rtables}, consider reading through the {rtables} Developer Guide. The Developer Guide can be accessed from the {rtables} site navigation bar, and is listed here for your convenience:
The {rtables} package follows the tidyverse style guide so please adhere to these guidelines in your submitted code. After making changes to a file within the package, you can apply the package styler automatically and check for lint by running the following two lines of code while within the file:
styler:::style_active_file() lintr:::addin_lint()
Package documentation uses roxygen2. If your contribution requires updates to documentation, ensure that the roxygen comments are updated within the source code file. After updating roxygen documentation, run devtools::document() to update the accompanying .Rd files (do not update these files by hand!).
roxygen2
devtools::document()
.Rd
To ensure high code coverage, we create tests using the testthat package. In most cases, changes to package code necessitate the addition of one or more tests to ensure that any added features are working as expected and no existing features were broken.
testthat
After making updates to the package, please add a descriptive entry to the NEWS file that reflects your changes. See the tidyverse style guide for guidelines on creating a NEWS entry.
Once the previous two steps are complete, you can create a pull request. Indicate in the description which issue is addressed in the pull request, and again utilize labels to help reviewers identify the category of the changes contained within the pull request.
Once your pull request has been created, a series of checks will be automatically triggered, including R CMD check, tests/code coverage, auto-documentation, and more. All checks must be passing in order to eventually merge your pull request, and further changes may be required in order to resolve the status of these checks. All pull requests must also be reviewed and approved by at least one of the package maintainers before they can be merged. A review will be automatically requested from several {rtables} maintainers upon creating your pull request. When a maintainer reviews your pull request, please try to address the comments in short order - the {rtables} package is updated on a regular basis and leaving a pull request open too long is likely to result in merge conflicts which create more work for the developer.
R CMD check
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
Please briefly describe your problem and, when relevant, the output you expect. Please also provide the output of utils::sessionInfo() or devtools::session_info() at the end of your post.
utils::sessionInfo()
devtools::session_info()
If at all possible, please include a minimal, reproducible example. The rtables team will be much more likely to resolve your issue if they are able to reproduce it themselves locally.
rtables
Please delete this preamble after you have read it.
your brief description of the problem
library(rtables) # your reproducible example here
Articles intended for developer use only.
Therefore, a fundamental difference between pruning and sorting is that sorting occurs at particular places in the table, as defined by a @@ -919,7 +901,7 @@
We see that a similar function to cont_n_allcols() is wrapped by one that allows a parameter j to be used to diff --git a/main/articles/split_functions.html b/main/articles/split_functions.html index b8fd1f6c7..26b6860ae 100644 --- a/main/articles/split_functions.html +++ b/main/articles/split_functions.html @@ -1,4 +1,5 @@ - + +
cont_n_allcols()
j
Gabriel Becker. Author. Original creator of the package
F. Hoffmann-La Roche AG. Copyright holder, funder.
Becker G, Waddell A (2024). rtables: Reporting Tables. -R package version 0.6.10.9005, +R package version 0.6.10.9006, https://insightsengineering.github.io/rtables/, https://github.com/insightsengineering/rtables.
@Manual{, title = {rtables: Reporting Tables}, author = {Gabriel Becker and Adrian Waddell}, year = {2024}, - note = {R package version 0.6.10.9005, + note = {R package version 0.6.10.9006, https://insightsengineering.github.io/rtables/}, url = {https://github.com/insightsengineering/rtables}, }
tt_as_flextable()
export_as_docx()
.docx
as_result_df()
make_ard
docx
rtables.officer
as_strings
as_viewer
data_format = c("full_precision", "strings", "numeric")
spec
result_df_specs()
as_is
simplify
flextable
TableTree
analyze
NA
var_labels
CRAN release: 2024-09-20
section_properties_default()
.html
bold_titles
tt_to_flextable()
reorder_split_levels()
tt
theme_docx_default()
"\n"
as_html
expand_newlines = FALSE
keep_split_levels()
""
" "
sep = "\t"
...
export_as_tsv
matrix_form
toString
simple_analysis
theme_html_default()
CRAN release: 2024-06-27
col_counts
macOS
CRAN release: 2024-06-20
truetype
formatters
>= 0.5.8
fontspec
make_split_fun
core_split
facet_colcount
facet_colcounts_visible
rm_all_colcounts
Viewer
col_counts<-
col_total<-
value
col_gap
nlines
make_row_df
lifecycle
gap
check_headers
rbindl_rtables
CRAN release: 2024-04-15
top_level_section_div
basic_table
keep_label_rows
as_result_df
sort_at_path
rlistings
mform_handle_newlines
rtables_root
"root"
tt_at_path
\n
add_analyzed_var
trim_zero_rows
CRAN release: 2023-12-08
ref_group
bold
header_sep_line
na_str
analyze_colvars
data.frame
expand_colnames
export_as_pdf
row_paths()
styler
col_fnotes_here
col_footnotes
txt
stringi
checkmate
.df_row
CRAN release: 2023-08-30
cfun/afun
.alt_df_row
.alt_df
alt_counts_df
.all_col_exprs
.all_col_counts
rbind
.spl_context
cur_col_id
cur_col_expr
cur_col_split
cur_col_split_val
qtable
qtable_layout
row_labels
df
formatters::check_aligns
chk_rtables_align
formatters::list_valid_aligns
rtables_aligns
page_by
split_rows_by
var
lblvar
sanitize_table_struct
validate_table_struct
find_degen_struct
CRAN release: 2023-05-25
paginate_table
cpp
lpp
font_size
export_as_txt
export_as_rtf
r2rtf
split_label
split_rows_by_multivar
extra_args
split_cols_by_multivar
CRAN release: 2023-03-02
colcount_format
>=0.4.0
[<-
i
[
CellValue
formatters::page_lcpp
>= 0.3.3.2
page_lcpp
vpaginate_table
>=0.3.2.4
section_div
split_rows_by*
>=0.3.2.3
add_combo_levels
path
cbind
CRAN release: 2022-05-21
linesep
hsep
horizontal_sep
horizontal_sep<-
split_rows_by(var, child_labels="hidden")
CRAN release: 2022-04-01
formatable
>=0.2.0
cfun
path_enriched_df
tsv
table_shell
CRAN release: 2021-10-06
NULL
insert_rrow
insert_row_at_path
label_at_path<-
value_at
cell_values
TableRow
trim_levels_to_map
[@wwojciech](https://github.com/wwojciech)
fnotes_at_path<-
tablerow
multivar
CRAN release: 2021-07-13
vars_in_layout
Synchronize release with GitHub commit sha.
sha
CRAN release: 2021-01-22
Documentation revisions as requested by CRAN. No change to package code.
Documentation-text only changes to introduction vignette to pass CRAN’s URL checks. All package, example, test, and vignette code fully identical to that in tagged GitHub release 0.3.4
Minor changes to the 0.3.3 version in order to submit rtables to CRAN.
This version completely refactors the rtables package. We do provide a backwards compatibility layer with the rtable, rcell, rrow, rheader, and rtabulate family of functions. However the table data structure and main tabulation framework have changed. We provide extensive documentation in the manuals help(package = "rtables") and vignettes vignette(package = "rtables") of the package.
rtable
rcell
rrow
rheader
rtabulate
help(package = "rtables")
vignette(package = "rtables")
The changes to rtables have been undertaken to better meet the requirements of creating and analyzing & reporting tables in the context of clinical trials.
make_afun
force()
lapply
inclNAs
make_pagdf
.in_ref_col
.ref_group
"multivars"
MultiVarSplit
summarize_row_groups
value_formats
in_rows
cbind_rtables
xx.xx (xx.xx - xx.xx)
x.xxxx | (<0.0001)
col_by
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
label
var_labels<-
var_labels_remove
var_relabel
with_label
cbing_rtables
empty_rtables
is_empty_rtable
is_non_empty_rtable
is_rtable
header_indent<-
header_row.names
header_row.names<-
rbind.rtable
rbind(tbl1, rrow(), tbl2)
rbind(tbl1, rrow("row name"), tbl2)
indent
header_add_N
rtablulate
row_*_data_args
col_wise_args
order_rrows
sort_rrows
order_rtables
sort_rtables
unlist.rtables
shiny.tag
htmltools
as.html
class.table
class.tr
class.th
class.td
sprintf_format
"(N=xx)"
">999.9"
col_N
col_N()
0.1.0
header
col.names
c("A", "B")
row.name
header<-
get_rcell_formats
list_rcell_format_labels
indented_row.names
CellValue( val, format = NULL, @@ -139,79 +85,65 @@ Usage
(ANY) value in the cell exactly as it should be passed to a formatter or returned when extracted.
ANY
(string, function, or list) 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.
string
function
list
"xx.x"
formatters::list_valid_format_labels()
(integer(1)) column span value.
integer(1)
(string) a label (not to be confused with the name) for the object/structure.
(numeric) 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.
numeric
(list or NULL) referential footnote messages for the cell.
(string or NULL) alignment the value should be rendered with. Defaults to "center" if NULL is used. See formatters::list_valid_aligns() for all currently supported alignments.
"center"
formatters::list_valid_aligns()
(string) string which should be displayed when formatted if this cell's value(s) are all NA.
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.
ManualSplit( levels, label, @@ -142,103 +88,85 @@ Usage
(character) levels of the split (i.e. the children of the manual split).
character
(string) name of the split/table/row being created. Defaults to the value of the corresponding label, but is not required to be.
(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 not match a formal argument of the tabulation function.
(numeric(1)) the indent modifier for the content tables generated by this split.
numeric(1)
(string) the variable, if any, that the content function should accept. Defaults to NA.
(list) extra arguments to be passed to the content function when tabulating row group summaries.
(string) 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.
"hidden"
"visible"
"topleft"
"default"
(string) prefix to be appended with the split value when forcing pagination between the children of a split/table.
(string) 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.
NA_character_
A ManualSplit object.
ManualSplit
Gabriel Becker
MultiVarSplit( vars, split_label = "", @@ -153,167 +99,138 @@ Usage
(character) vector of variable names.
(string) 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).
(character) vector of labels for vars.
vars
(character) 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.
(list, function, or NULL) 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().
x
labelstr
analyze()
(string, function, or list) format for content rows.
(character) NA string for use with cformat for content table.
cformat
(string, function, or list) default format associated with the split being created.
(character) NA string vector for use with split_format.
split_format
(string) name associated with the split (for pathing, etc.).
(string) 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.
(function or NULL) custom splitting function. See custom_split_funs.
(logical(1)) should column counts be displayed at the level facets created by this split. Defaults to FALSE.
logical(1)
FALSE
(character(1)) if show_colcounts is TRUE, the format which should be used to display column counts for facets generated by this split. Defaults to "(N=xx)".
character(1)
show_colcounts
TRUE
A MultiVarSplit object.
VarLevelSplit( var, split_label, @@ -173,177 +119,146 @@ Usage
(string) variable name.
(string) name of variable containing labels to be displayed for the values of var.
(character) the order that the split children should appear in resulting table.
(character) value of var to be taken as the ref_group/control to be compared against.
(string) 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".
sprintf
"\%s"
a VarLevelSplit object.
VarLevelSplit
Viewer(x, y = NULL, ...)
(rtable or shiny.tag) an object of class rtable or shiny.tag (defined in htmltools package).
(rtable or shiny.tag) optional second argument of same type as x.
arguments passed to as_html().
as_html()
Not meaningful. Called for the side effect of opening a browser or viewer pane.
if (interactive()) { sl5 <- factor(iris$Sepal.Length > 5, levels = c(TRUE, FALSE), @@ -188,19 +126,17 @@ ExamplesOn this page - -
add_colcounts(lyt, format = "(N=xx)")
(PreDataTableLayouts) layout object pre-data used for tabulation.
PreDataTableLayouts
A PreDataTableLayouts object suitable for passing to further layouting functions, and to build_table().
build_table()
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. 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.
lyt <- basic_table() %>% split_cols_by("ARM") %>% add_colcounts() %>% @@ -203,19 +140,17 @@ ExamplesOn this page - -
add_combo_facet(name, label = name, levels, extra = list()) add_overall_facet(name, label, extra = list())
(string) name for the resulting facet (for use in pathing, etc.).
(string) label for the resulting facet.
(character) vector of levels to combine within the resulting facet.
(list) extra arguments to be passed to analysis functions applied within the resulting facet.
A function which can be used within the post argument in make_split_fun().
post
make_split_fun()
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.
add_combo_facet
levels
Other make_custom_split: drop_facet_levels(), make_split_fun(), make_split_result(), -trim_levels_in_facets()
drop_facet_levels()
make_split_result()
trim_levels_in_facets()
mysplfun <- make_split_fun(post = list( add_combo_facet("A_B", label = "Arms A+B", @@ -203,19 +136,17 @@ ExamplesOn this page - -
add_existing_table(lyt, tt, indent_mod = 0)
(TableTree or related class) a TableTree object representing a populated table.
lyt1 <- basic_table() %>% split_cols_by("ARM") %>% analyze("AGE", afun = mean, format = "xx.xx") @@ -202,19 +139,17 @@ ExamplesOn this page - -
add_overall_col(lyt, label)
add_overall_level()
lyt <- basic_table() %>% split_cols_by("ARM") %>% add_overall_col("All Patients") %>% @@ -187,19 +125,17 @@ ExamplesOn this page - -
add_overall_level( valname = "Overall", label = valname, @@ -149,78 +95,63 @@ Usage
An object of class AllLevelsSentinel of length 0.
AllLevelsSentinel
(string) value to be assigned to the implicit all-observations split level. Defaults to "Overall".
"Overall"
(flag) whether the implicit level should appear first (TRUE) or last (FALSE). Defaults to TRUE.
flag
(flag) whether splits corresponding with 0 observations should be kept when tabulating.
(data.frame or tbl_df) 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.
tbl_df
valname
levelcombo
exargs
select_all_levels
comblevels
(character or NULL) if non-NULL, the levels to retain across both combination and individual levels.
A splitting function (splfun) that adds or changes the levels of a split.
splfun
Analysis or summary functions for which the order matters should never be used within the tabulation framework.
custom_split_funs and split_funcs.
lyt <- basic_table() %>% split_cols_by("ARM", split_fun = add_overall_level("All Patients", first = FALSE @@ -341,19 +272,17 @@ ExamplesOn this page - -
We list and describe all the parameters that can be added to a custom analysis function below:
Column-wise N (column count) for the full column being tabulated within.
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 @@ -197,19 +140,17 @@
split_rows_by()
analyze( lyt, vars, @@ -150,129 +96,105 @@ Usage
(function) 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().
(character) vector of labels for one or more variables.
(character) names for the tables representing each atomic analysis. Defaults to var.
(string) string that should be displayed when the value of x is missing. Defaults to "NA".
"NA"
(logical) 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.
logical
(logical) whether NA observations in the var variable(s) should be included when performing the analysis. Defaults to FALSE.
(string) whether the variable labels corresponding to the variable(s) in vars should be visible in the resulting table.
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.
format
afun
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:
If afun's first parameter is x, it will receive the corresponding subset vector of data from the relevant +function accepts will change the behavior when tabulation is performed as follows:
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.
In addition to differentiation on the first argument, the analysis function can optionally accept a number of +
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.
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.
make_afun()
.N_col
.N_total
lyt <- basic_table() %>% split_cols_by("ARM") %>% analyze("AGE", afun = list_wrap_x(summary), format = "xx.xx") @@ -335,19 +257,17 @@ ExamplesOn this page - -
analyze_colvars( lyt, afun, @@ -139,83 +85,68 @@ Usage
(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.
split_cols_by_multivar()
library(dplyr) ANL <- DM %>% mutate(value = rnorm(n()), pctdiff = runif(n())) @@ -284,19 +215,17 @@ ExamplesOn this page - -
append_topleft(lyt, newlines)
(character) the new line(s) to be added to the materials.
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).
newlines
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.
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.
top_left()
library(dplyr) DM2 <- DM %>% mutate(RACE = factor(RACE), SEX = factor(SEX)) @@ -201,19 +137,17 @@ ExamplesOn this page - -
as_html( x, width = NULL, @@ -141,77 +87,62 @@ Usage
(VTableTree) a TableTree object.
VTableTree
(character) 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.
"100%"
"300px"
(character) class for table tag.
table
(character) class for tr tag.
tr
(character) class for th tag.
th
(character) link anchor label (not including tab: prefix) for the table.
tab:
(character) 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".
"main_title"
"subtitles"
"header"
"row_names"
"label_rows"
"content_rows"
(flag) whether a black line should be printed to under the table header. Defaults to TRUE.
(flag) whether spaces between table cells should be collapsed. Defaults to FALSE.
(flag) Defaults to FALSE, relying on html output to solve newline characters (\n). Doing this keeps the structure of the cells but may depend on the output device.
html
A shiny.tag object representing x in HTML.
tbl <- rtable( header = LETTERS[1:3], format = "xx", @@ -341,19 +272,17 @@ ExamplesOn this page - -
# S4 method for class 'VTableTree' as.vector(x, mode = "any")
(ANY) the object to be converted to a vector.
(string) passed on to as.vector().
as.vector()
A vector of the chosen mode (or an error is raised if more than one row was present).
This only works for a table with a single row or a row object.
AnalyzeVarSplit( var, split_label = var, @@ -185,144 +131,119 @@ Usage
(character) default row labels, if not specified by the return value of afun.
(list) used internally, not intended to be set by end users.
(character) names to be given to the subsplits contained by a compound split (typically an AnalyzeMultiVars split object).
AnalyzeMultiVars
An AnalyzeVarSplit object.
AnalyzeVarSplit
An AnalyzeMultiVars split object.
basic_table( title = "", subtitles = character(), @@ -140,36 +86,29 @@ Usage
(string) single string to use as main title (formatters::main_title()). Ignored for subtables.
formatters::main_title()
(character) a vector of strings to use as subtitles (formatters::subtitles()), where every element is printed on a separate line. Ignored for subtables.
formatters::subtitles()
(character) a vector of strings to use as main global (non-referential) footer materials (formatters::main_footer()), where every element is printed on a separate line.
formatters::main_footer()
(character) a vector of strings to use as provenance-related global footer materials (formatters::prov_footer()), where every element is printed on a separate line.
formatters::prov_footer()
(logical(1)) Indicates whether the lowest level of applied to data. NA, the default, indicates that the show_colcounts argument(s) passed to the relevant calls to split_cols_by* @@ -178,42 +117,35 @@
split_cols_by*
(string) format for use when displaying the column counts. Must be 1d, or 2d where one component is a percent. This will also apply to any displayed higher level column counts where an explicit format was not specified. Defaults to "(N=xx)". See Details below.
(string) 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.
header_section_div()
section_div()
(character(1)) 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.
(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).
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, @@ -222,22 +154,18 @@
1
Because percent components in colcount_format are always populated with the value 1, we can get arguably +
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 (formatters::subtitles()) and footers (formatters::main_footer() and formatters::prov_footer()) that span more than one line can be supplied as a character vector to maintain indentation on multiple lines.
lyt <- basic_table() %>% analyze("AGE", afun = mean) @@ -273,7 +201,7 @@ Examples#> #> test footer #> -#> test.R program, executed at 2024-11-27 09:02:43.623434 +#> test.R program, executed at 2024-11-27 09:16:18.266694 lyt3 <- basic_table( show_colcounts = TRUE, @@ -284,19 +212,17 @@ ExamplesOn this page - -
R/tt_pos_and_access.R
brackets.Rd
# S4 method for class 'VTableTree,ANY,ANY,list' x[i, j, ...] <- value @@ -135,32 +80,23 @@ Usage
(TableTree) a TableTree object.
(numeric(1)) index.
additional arguments. Includes:
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.
(list, TableRow, or TableTree) replacement value.
(flag) 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.
cell_values()
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.
ElementaryTable
drop = TRUE
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.
topleft
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 [<-.
sort_at_path()
sort_at_path() to understand sorting.
summarize_row_groups() to understand path structure.
summarize_row_groups()
lyt <- basic_table( title = "Title", subtitles = c("Sub", "titles"), @@ -522,19 +447,17 @@ ExamplesOn this page - -
build_table( lyt, df, @@ -142,68 +88,55 @@ Usage
(data.frame or tibble) dataset.
tibble
(data.frame or tibble) alternative full dataset the rtables framework will use only when calculating column counts.
(numeric or NULL) if non-NULL, column counts for leaf-columns only which override those calculated automatically during tabulation. Must specify "counts" for all leaf-columns if non-NULL. NA elements will be replaced with the automatically calculated counts. Turns on display of leaf-column counts when non-NULL.
(integer(1)) the total observations across all columns. Defaults to nrow(df).
nrow(df)
(character) override values for the "top left" material to be displayed during printing.
(string) 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.
-
formatters::set_default_hsep()
ignored.
A TableTree or ElementaryTable object representing the table created by performing the tabulations declared in lyt to the data df.
lyt
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.
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.
length()
nrow()
lyt <- basic_table() %>% split_cols_by("Species") %>% analyze("Sepal.Length", afun = function(x) { @@ -332,19 +262,17 @@ ExamplesOn this page - -
cbind_rtables(x, ..., sync_count_vis = TRUE)
(TableTree or TableRow) a table or row object.
one or more further objects of the same class as x.
(logical(1)) should column count visibility be synced across the new and existing columns. Currently defaults to TRUE for backwards compatibility but this may change in future releases.
A formal table object.
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)) @@ -198,19 +136,17 @@ ExamplesOn this page - -
cell_values(tt, rowpath = NULL, colpath = NULL, omit_labrows = TRUE) value_at(tt, rowpath = NULL, colpath = NULL) @@ -135,55 +81,43 @@ Usage
(character) path in row-split space to the desired row(s). Can include "@content".
"@content"
(character) path in column-split space to the desired column(s). Can include "*".
"*"
(flag) whether label rows underneath rowpath should be omitted (TRUE, the default), or return empty lists of cell "values" (FALSE).
rowpath
cell_values returns a list (regardless of the type of value the cells hold). If rowpath defines a path to +
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.
colpath
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.
cell_values will return a single cell's value wrapped in a list. Use value_at to receive the "bare" cell value.
lyt <- basic_table() %>% split_cols_by("ARM") %>% split_cols_by("SEX") %>% @@ -350,19 +284,17 @@ ExamplesOn this page - -
InstantiatedColumnInfo( treelyt = LayoutColTree(colcount = total_cnt), csubs = list(expression(TRUE)), @@ -140,79 +86,64 @@ Usage
(LayoutColTree) a LayoutColTree object.
LayoutColTree
(list) a list of subsetting expressions.
(list) extra arguments associated with the columns.
(integer) counts.
integer
(integer(1)) total observations represented across all columns.
(flag) whether the counts should be displayed as header info when the associated table is printed.
(string) format for the counts if they are displayed.
(character) string to use in place of missing values when formatting counts. Defaults to "".
An InstantiateadColumnInfo object.
InstantiateadColumnInfo
clear_indent_mods(tt) # S4 method for class 'VTableTree' @@ -136,26 +82,20 @@ Usage
The same class as tt, with all indent modifiers set to zero.
lyt1 <- basic_table() %>% summarize_row_groups("STUDYID", label_fstr = "overall summary") %>% split_rows_by("AEBODSYS", child_labels = "visible") %>% @@ -217,19 +157,17 @@ ExamplesOn this page - -
clayout(obj) # S4 method for class 'VTableNodeInfo' @@ -265,83 +211,68 @@ Usage
(ANY) the object for the accessor to access or modify.
(ANY) the object to modify in place.
(ANY) the new value.
(data.frame or NULL) data to use if the column information is being generated from a pre-data layout object.
(TreePos) root position.
TreePos
(FormatSpec) The format to be used by default for column counts throughout this column tree (i.e. if not overridden by a more specific format specification).
FormatSpec
(character or NULL)col_counts accessor and setter only. Path (in column structure).
A LayoutColTree object.
Returns various information about columns, depending on the accessor used.
facet_colcount()
colcount_visible(obj, path) # S4 method for class 'VTableTree' @@ -150,31 +96,24 @@ Usage
(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.
for colcount_visible a logical scalar indicating whether the specified position in the column hierarchy is set to display its column count; @@ -182,8 +121,7 @@
colcount_visible
Users generally should not call colcount_visible directly, as setting sibling facets to have differing column count visibility will result in an error when @@ -191,19 +129,17 @@
R/tree_accessors.R
collect_leaves.Rd
collect_leaves(tt, incl.cont = TRUE, add.labrows = FALSE)
(flag) whether to include rows from content tables within the tree. Defaults to TRUE.
(flag) whether to include label rows. Defaults to FALSE.
A list of TableRow objects for all rows in the table.
coltree_structure(obj)
Nothing, called for its side effect of displaying a summary to the terminal.
lyt <- basic_table() %>% split_cols_by("ARM") %>% split_cols_by("STRATA1") %>% @@ -184,19 +124,17 @@ ExamplesOn this page - -
compare_rtables( object, expected, @@ -148,56 +94,45 @@ Usage
(VTableTree)rtable to test.
(VTableTree) expected rtable.
(numeric(1)) tolerance.
(flag) whether to compare cell formats. Other attributes are silently ignored.
(flag) 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.
A matrix of class rtables_diff representing the differences between object and expected as described above.
rtables_diff
object
expected
In its current form, compare_rtables does not take structure into account, only row and cell position.
compare_rtables
t1 <- rtable(header = c("A", "B"), format = "xx", rrow("row 1", 1, 2)) t2 <- rtable(header = c("A", "B", "C"), format = "xx", rrow("row 1", 1, 2, 3)) @@ -309,19 +244,17 @@ ExamplesOn this page - -
compat_args(.lst, row.name, format, indent, label, inset)
(list) an already-collected list of arguments to be used instead of the elements of .... Arguments passed via ... will be ignored if this is specified.
(string or NULL) row name. If NULL, an empty string is used as row.name of the rrow().
rrow()
(string, function, or list) 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.
(integer(1)) the table inset for the row or table being constructed. See formatters::table_inset() for details.
formatters::table_inset()
No return value.
Other conventions: constr_args(), gen_args(), @@ -186,19 +121,17 @@
constr_args()
gen_args()
constr_args( kids, cont, @@ -159,180 +105,147 @@ Usage
(list) list of direct children.
(ElementaryTable) content table.
(integer(1)) nesting level (roughly, indentation level in practical terms).
(flag) whether the TableTree/ElementaryTable is being constructed as the content table for another TableTree.
(InstantiatedColumnInfo or NULL) column structure for the object being created.
InstantiatedColumnInfo
(LabelRow) the LabelRow object to assign to the table. Constructed from label by default if not specified.
LabelRow
(list) cell values for the row.
(integer) column span. 1 indicates no spanning.
(list or NULL) referential footnotes to be applied at current level. In post-processing, this can be achieved with fnotes_at_path<-.
(character) page-specific title(s).
(string) 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.
(numeric(1)) 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).
Other conventions: compat_args(), gen_args(), @@ -341,19 +254,17 @@
compat_args()
content_table.Rd
content_table(obj) content_table(obj) <- value
(TableTree) the table object.
(ElementaryTable) the new content table for obj.
obj
the ElementaryTable containing the (top level) content rows of obj (or NULL if obj is not a formal table object).
counts_wpcts(x, .N_col)
(factor) a vector of data, provided by rtables pagination machinery.
factor
(integer(1)) total count for the column, provided by rtables pagination machinery.
A RowsVerticalSection object with counts (and percents) for each level of the factor.
RowsVerticalSection
counts_wpcts(DM$SEX, 400) #> RowsVerticalSection (in_rows) object print method: #> ---------------------------- @@ -167,19 +106,17 @@ ExamplesOn this page - -
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:
a data.frame of incoming data to be split.
The function must then output a named list with the following elements:
the vector of all values corresponding to the splits of df.
One way to generate custom splitting functions is to wrap existing split functions and modify either the incoming +
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.
make_split_fun() for the API for creating custom split functions, and split_funcs for a variety of pre-defined split functions.
# Example of a picky split function. The number of values in the column variable # var decrees if we are going to print also the column with all observation # or not. @@ -237,19 +176,17 @@ ExamplesOn this page - -
make_static_cut_split( var, split_label, @@ -181,173 +127,143 @@ Usage
(numeric) cuts to use.
(character or NULL) labels for the cuts.
(flag) whether the cuts should be treated as cumulative. Defaults to FALSE.
(function) function which accepts the full vector of var values and returns cut points to be used (via cut) when splitting data during tabulation.
cut
(function) function which returns either labels for the cuts or NULL when passed the return value of cutfun.
cutfun
A VarStaticCutSplit, CumulativeCutSplit object for make_static_cut_split, or a VarDynCutSplit object for VarDynCutSplit().
VarStaticCutSplit
CumulativeCutSplit
make_static_cut_split
VarDynCutSplit
VarDynCutSplit()
as_result_df( tt, spec = NULL, @@ -141,101 +87,78 @@ Usage
(function) function that generates the result data frame from a table (TableTree). It defaults to NULL, for standard processing.
(string) the format of the data in the result data frame. It can be one value between "full_precision" (default), "strings", and "numeric". The last two values show the numeric data with the visible precision.
"full_precision"
"strings"
"numeric"
(flag) when TRUE, the result data frame will have only one statistic per row.
(flag) 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.
(flag) when TRUE, the result data frame will have all labels as they appear in the final table.
(flag) when TRUE, the result data frame will have only visible labels and result columns. Consider showing also label rows with keep_label_rows = TRUE. This output can be used again to create a TableTree object with df_to_tt().
keep_label_rows = TRUE
df_to_tt()
additional arguments passed to spec-specific result data frame function (spec).
(function) function to transform paths into single-string row/column names.
(function) 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 |.
collapse_values
|
as_result_df returns a result data.frame.
path_enriched_df() returns a data.frame of tt's cell values (processed by value_fun, with columns named by +
path_enriched_df()
value_fun
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).
path_fun
row_path
path_enriched_df(): Transform a TableTree object to a path-enriched data.frame.
df_to_tt() when using simplify = TRUE and formatters::make_row_df() to have a comprehensive view of the hierarchical structure of the rows.
simplify = TRUE
formatters::make_row_df()
lyt <- basic_table() %>% split_cols_by("ARM") %>% split_rows_by("STRATA1") %>% @@ -272,19 +195,17 @@ ExamplesOn this page - -
R/tt_from_df.R
df_to_tt.Rd
df_to_tt(df)
(data.frame) a data frame.
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.
label_name
as_is = TRUE
as_result_df() for the inverse operation.
df_to_tt(mtcars) #> mpg cyl disp hp drat wt qsec vs am gear carb #> ————————————————————————————————————————————————————————————————————————————————————————————— @@ -197,19 +135,17 @@ ExamplesOn this page - -
# S4 method for class 'VTableTree' nrow(x) @@ -137,26 +83,20 @@ Usage
(TableTree or ElementaryTable) a table object.
The number of rows (nrow), columns (ncol), or both (dim) of the object.
nrow
ncol
dim
lyt <- basic_table() %>% split_cols_by("ARM") %>% analyze(c("SEX", "AGE")) @@ -178,19 +118,17 @@ ExamplesOn this page - -
do_base_split(spl, df, vals = NULL, labels = NULL, trim = FALSE)
(Split) a Split object defining a partitioning or analysis/tabulation of the data.
Split
(ANY) already calculated/known values of the split. Generally should be left as NULL.
(character) labels associated with vals. Should be NULL whenever vals is, which should almost always be the case.
vals
(flag) whether groups corresponding to empty data subsets should be removed. Defaults to FALSE.
The result of the split being applied as if it had no custom split function. See custom_split_funs.
uneven_splfun <- function(df, spl, vals = NULL, labels = NULL, trim = FALSE) { ret <- do_base_split(spl, df, vals, labels, trim) if (NROW(df) == 0) { @@ -205,19 +141,17 @@ ExamplesOn this page - -
R/make_split_fun.R
drop_facet_levels.Rd
drop_facet_levels(df, spl, ...)
(data.frame) the incoming data corresponding with the parent facet.
(VarLevelSplit) the split.
additional parameters passed internally.
Other make_custom_split: add_combo_facet(), make_split_fun(), make_split_result(), -trim_levels_in_facets()
add_combo_facet()
facet_colcount(obj, path) # S4 method for class 'LayoutColTree' @@ -156,41 +102,33 @@ Usage
character. This path must end on a split value, e.g., the level of a categorical variable that was split on in column space, but it need not be the path to an individual column.
for facet_colcount the current count associated with that facet in column space, for facet_colcount<-, obj modified with the new column count for the specified facet.
facet_colcount<-
Updating a lower-level (more specific) column count manually will not update the counts for its parent facets. This cannot be made @@ -202,14 +140,12 @@
col_counts()
lyt <- basic_table() %>% split_cols_by("ARM", show_colcounts = TRUE) %>% split_cols_by("SEX", @@ -238,19 +174,17 @@ ExamplesOn this page - -
facet_colcounts_visible(obj, path) <- value
(character) the path to the parent of the desired siblings. The last element in the path should be a split name.
obj, modified with the desired column count. display behavior
colcount_visible()
find_degen_struct(tt)
A list of character vectors representing the row paths, if any, to degenerate substructures within the table.
Other table structure validation functions: sanitize_table_struct(), validate_table_struct()
sanitize_table_struct()
validate_table_struct()
find_degen_struct(rtable("hi")) #> [[1]] #> [1] "" @@ -171,19 +110,17 @@ ExamplesOn this page - -
format_rcell( x, format, @@ -138,58 +84,46 @@ Usage
(CellValue or ANY) an object of class CellValue, or a raw value.
(string or function) the format label or formatter function to apply to x.
(string) output type.
(list) list of default formats coming from the general row.
(list) list of default "NA" strings coming from the general row.
(flag) whether the formats themselves should be returned instead of the values with formats applied. Defaults to FALSE.
Formatted text.
cll <- CellValue(pi, format = "xx.xxx") format_rcell(cll) #> [1] "3.142" @@ -207,19 +141,17 @@ ExamplesOn this page - -
# S4 method for class 'VNodeInfo' obj_name(obj) @@ -308,114 +254,90 @@ Usage
(ANY) an object.
(numeric) a vector of column widths for use in vertical pagination.
(numeric(1)) width that strings should be wrapped to when determining how many lines they require.
(font_spec) a font_spec object specifying the font information to use for calculating string widths and heights, as returned by font_spec().
font_spec
font_spec()
(numeric(1)) width of gap between columns in number of spaces. Only used by methods which must calculate span widths after wrapping.
(flag) should only visible aspects of the table structure be reflected in this summary. Defaults to TRUE. May not be supported by all methods.
(numeric(1)) internal detail, do not set manually.
(integer(1)) internal detail, do not set manually.
(flag) internal detail, do not set manually.
(integer) internal detail, do not set manually.
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.
When visible_only is 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 @@ -427,35 +349,31 @@
visible_only
The technically present root tree node is excluded from the summary returned by both make_row_df and make_col_df (see relevant functions inrtables), as it is the row/column structure of tt and thus not useful for pathing or pagination.
make_col_df
# Expected error with matrix_form. For real case examples consult {rtables} documentation mf <- basic_matrix_form(iris) # make_row_df(mf) # Use table obj instead
gen_args( df, alt_counts_df, @@ -156,158 +102,128 @@ Usage
(numeric) which top-level set of nested splits should the new layout feature be added to. Defaults to the current split.
(TableRow or related class) a TableRow object representing a single row within a populated table.
(flag) whether additional information should be displayed to the user. Defaults to FALSE.
(numeric(1)) number of spaces to use per indent level. Defaults to 2.
additional parameters passed to methods or tabulation functions.
Other conventions: compat_args(), constr_args(), @@ -316,19 +232,17 @@
get_formatted_cells(obj, shell = FALSE) # S4 method for class 'TableTree' @@ -156,32 +102,25 @@ Usage
The formatted print-strings for all (body) cells in obj.
library(dplyr) iris2 <- iris %>% @@ -214,19 +153,17 @@ ExamplesOn this page - -
head(x, ...) # S4 method for class 'VTableTree' @@ -154,23 +100,18 @@ Usage
an object
arguments to be passed to or from other methods.
an integer vector of length up to dim(x) (or 1, for non-dimensioned objects). A logical is silently coerced to integer. Values specify the indices to be @@ -183,46 +124,39 @@
dim(x)
(flag) if TRUE (the default), top_left material for the table will be carried over to the subset.
(flag) if TRUE (the default), all title material for the table will be carried over to the subset.
(flag) if TRUE, all footer material for the table will be carried over to the subset. It defaults to keep_titles.
keep_titles
(flag) defaults to FALSE. If TRUE, referential footnotes will be reindexed for the subset.
horizontal_sep(obj) # S4 method for class 'VTableTree' @@ -141,47 +87,37 @@ Usage
(string) string to use as new header/body separator.
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.
in_rows( ..., .list = NULL, @@ -141,84 +87,67 @@ Usage
single row defining expressions.
(list) list cell content (usually rcells). The .list is concatenated to ....
rcells
.list
(character or NULL) names of the returned list/structure.
(character or NULL) labels for the defined rows.
(character or NULL) formats for the values.
(integer or NULL) indent modifications for the defined rows.
(list) referential footnote messages to be associated by name with cells.
(list) referential footnotes messages to be associated by name with rows.
(character or NULL) alignments for the cells. Standard for NULL is "center". See formatters::list_valid_aligns() for currently supported alignments.
(character or NULL) NA strings for the cells.
A RowsVerticalSection object (or NULL). The details of this object should be considered an internal implementation detail.
In post-processing, referential footnotes can also be added using row and column paths with fnotes_at_path<-.
in_rows(1, 2, 3, .names = c("a", "b", "c")) #> RowsVerticalSection (in_rows) object print method: #> ---------------------------- @@ -275,19 +204,17 @@ ExamplesOn this page - -
rrows
R/indent.R
indent.Rd
indent(x, by = 1)
(VTableTree) an rtable object.
(integer) number to increase indentation of rows by. Can be negative. If final indentation is less than 0, the indentation is set to 0.
x with its indent modifier incremented by by.
by
is_setosa <- iris$Species == "setosa" m_tbl <- rtable( header = rheader( @@ -192,19 +130,17 @@ ExamplesOn this page - -
indent_string(x, indent = 0, incr = 2, including_newline = TRUE)
(character) a character vector.
(numeric) a vector of non-negative integers of length length(x).
length(x)
(integer(1)) a non-negative number of spaces per indent level.
(flag) whether newlines should also be indented.
x, indented with left-padding with indent * incr white-spaces.
indent * incr
indent_string("a", 0) #> [1] "a" indent_string("a", 1) @@ -177,19 +114,17 @@ ExamplesOn this page - -
The following dummy functions are unexported and used to document argument conventions in the framework.
lyt_args()
sf_args()
Functions for declaring layout and tabulation
qtable_layout()
qtable()
basic_table()
append_topleft()
split_cols_by()
add_colcounts()
split_rows_by_multivar()
analyze_colvars()
split_cols_by_cuts()
split_rows_by_cuts()
split_cols_by_cutfun()
split_cols_by_quartiles()
split_rows_by_quartiles()
split_rows_by_cutfun()
add_overall_col()
add_existing_table()
table_inset()
`table_inset<-`()
Functions that are useful to be used with the analyze* functions.
analyze*
in_rows()
additional_fun_params
simple_analysis()
list_wrap_x()
list_wrap_df()
spl_context
spl_context_to_disp_path()
counts_wpcts()
add_combo_levels()
remove_split_levels()
drop_split_levels()
drop_and_remove_levels()
trim_levels_in_group()
trim_levels_to_map()
custom_split_funs
do_base_split()
add_overall_facet()
add_to_split_result()
spl_variable()
cell formatting.
format_rcell()
value_formats()
nrow(<VTableTree>)
ncol(<VTableNodeInfo>)
dim(<VTableNodeInfo>)
col_paths()
row_paths_summary()
col_paths_summary()
table_structure()
table_shell()
table_shell_str()
make_row_df()
make_col_df()
vars_in_layout()
coltree_structure()
value_at()
`top_left<-`()
rbindl_rtables()
rbind(<VTableNodeInfo>)
rbind2(<VTableNodeInfo>,<ANY>)
cbind_rtables()
as.vector(<VTableTree>)
`[<-`(<VTableTree>,<ANY>,<ANY>,<list>)
`[`(<VTableTree>,<logical>,<logical>)
clear_indent_mods()
head()
tail()
`section_div<-`()
`header_section_div<-`()
top_level_section_div()
`top_level_section_div<-`()
`colcount_visible<-`()
`facet_colcount<-`()
`facet_colcounts_visible<-`()
rm_all_colcounts()
assert_valid_table()
find_degen_struct()
prune_table()
all_zero_or_na()
all_zero()
content_all_zeros_nas()
prune_empty_level()
prune_zeros_only()
low_obs_pruner()
trim_rows()
cont_n_onecol()
TableTrees
These functions provide some backwards compatibility to the previous (pre 2021) rtables framework.
rtable()
rtablel()
rcell()
non_ref_rcell()
rheader()
rrowl()
indent()
These functions create ascii or html representations of the table
export_as_tsv()
import_from_tsv()
toString(<VTableTree>)
get_formatted_cells()
get_cell_aligns()
utility functions
Viewer()
compare_rtables()
indent_string()
is_rtable()
Pagination related functionality
pag_tt_indices()
paginate_table()
content_table()
`content_table<-`()
tree_children()
`tree_children<-`()
collect_leaves()
obj_avar()
row_cells()
`row_cells<-`()
row_values()
`row_values<-`()
no_colinfo()
tern
clayout()
`clayout<-`()
col_info()
`col_info<-`()
coltree()
col_exprs()
`col_counts<-`()
col_total()
`col_total<-`()
horizontal_sep()
`horizontal_sep<-`()
main_title()
`main_title<-`()
subtitles()
`subtitles<-`()
page_titles()
`page_titles<-`()
main_footer()
`main_footer<-`()
prov_footer()
`prov_footer<-`()
all_footers()
all_titles()
obj_name()
`obj_name<-`()
obj_label()
`obj_label<-`()
obj_format()
`obj_format<-`()
obj_na_str()
`obj_na_str<-`()
obj_align()
`obj_align<-`()
S4 classes and constructors
manual_cols()
CellValue()
EmptyColInfo
EmptyElTable
EmptyRootSplit
EmptyAllSplit
ManualSplit()
MultiVarSplit()
VarLevelSplit()
VarLevWBaselineSplit()
AnalyzeVarSplit()
AnalyzeColVarSplit()
AnalyzeMultiVars()
make_static_cut_split()
InstantiatedColumnInfo()
LabelRow()
.tablerow()
DataRow()
ContentRow()
ElementaryTable()
TableTree()
Pathing and insertion related functions
label_at_path()
`label_at_path<-`()
tt_at_path()
`tt_at_path<-`()
insert_row_at_path()
Functions related to referential footnotes
row_footnotes()
`row_footnotes<-`()
cell_footnotes()
`cell_footnotes<-`()
col_fnotes_here()
`col_fnotes_here<-`()
col_footnotes()
`col_footnotes<-`()
ref_index()
`ref_index<-`()
ref_symbol()
`ref_symbol<-`()
ref_msg()
`fnotes_at_path<-`()
update_ref_indexing()
Functions for generating result data frames from rtables TableTree objects
insert_row_at_path(tt, path, value, after = FALSE) # S4 method for class 'VTableTree,DataRow' @@ -139,43 +85,34 @@ Usage
(flag) whether value should be added as a row directly before (FALSE, the default) or after (TRUE) the row specified by path.
DataRow(), rrow()
lyt <- basic_table() %>% split_rows_by("COUNTRY", split_fun = keep_split_levels(c("CHN", "USA"))) %>% analyze("AGE") @@ -212,19 +149,17 @@ ExamplesOn this page - -
insert_rrow(tbl, rrow, at = 1, ascontent = FALSE)
(VTableTree) a rtable object.
(TableRow) an rrow to append to tbl.
tbl
(integer(1)) position into which to put the rrow, defaults to beginning (i.e. row 1).
(flag) currently ignored.
A TableTree of the same specific class as tbl.
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.
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.
o <- options(warn = 0) lyt <- basic_table() %>% split_cols_by("Species") %>% @@ -262,19 +197,17 @@ ExamplesOn this page - -
# S4 method for class 'SplitVector' c(x, ...) @@ -1194,240 +1140,195 @@ Usage
(ANY) the object.
splits or SplitVector objects.
SplitVector
(Split) the split.
(numeric(1)) intended for internal use.
(function) intended for internal use.
(function) constructor function.
(numeric(1)) depth in tree.
(numeric(1)) indent.
(numeric(1)) indent for printing.
(VTableTree) a table object.
(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.
utils::str
(flag) whether split is an analyze split.
(flag) whether to override attribute.
(character or NULL) path within row structure. NULL indicates the footnote should go on the column rather than cell.
(character or NULL) path within column structure. NULL indicates footnote should go on the row rather than cell.
(flag) whether the numbering for referential footnotes should be immediately recalculated. Defaults to TRUE.
(ANY) second element to be row-bound via rbind2.
rbind2
Various, but should be considered implementation details.
library(dplyr) iris2 <- iris %>% @@ -1463,19 +1364,17 @@ ExamplesOn this page - -
R/utils.R
is_rtable.Rd
is_rtable(x)
TRUE if x is a formal TableTree object, FALSE otherwise.
is_rtable(build_table(basic_table(), iris)) #> [1] TRUE
label_at_path(tt, path) label_at_path(tt, path) <- value
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, @@ -164,16 +103,14 @@
labelrow
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.
lyt <- basic_table() %>% split_rows_by("COUNTRY", split_fun = keep_split_levels(c("CHN", "USA"))) %>% analyze("AGE") @@ -195,19 +132,17 @@ ExamplesOn this page - -
# S4 method for class 'CellValue' length(x)
(CellValue) a CellValue object.
Always returns 1L.
1L
list_wrap_x(f) list_wrap_df(f)
(function) the function to wrap.
A function that returns a list of CellValue objects.
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.
list_wrap_x
list_wrap_df
We provide both because when using the functions as tabulation in analyze(), functions which take df as @@ -158,14 +98,12 @@
summary(iris$Sepal.Length) #> Min. 1st Qu. Median Mean 3rd Qu. Max. #> 4.300 5.100 5.800 5.843 6.400 7.900 @@ -215,19 +153,17 @@ ExamplesOn this page - -
lyt_args( lyt, var, @@ -177,286 +123,235 @@ Usage
(function or 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 function.
(flag) 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.
Other conventions: compat_args(), constr_args(), @@ -465,19 +360,17 @@
make_afun( fun, .stats = NULL, @@ -140,84 +86,68 @@ Usage
(function) the function to be wrapped in a new customized analysis function. fun should return a named list.
fun
(character) names of elements to keep from fun's full output.
(ANY) vector or list of formats to override any defaults applied by fun.
(character) vector of labels to override defaults returned by fun.
(integer) named vector of indent modifiers for the generated rows.
(character) vector of names, which must match elements of .stats.
.stats
(ANY) vector/list of NA strings to override any defaults applied by fun.
additional arguments to fun which effectively become new defaults. These can still be overridden by extra_args within a split.
(flag) 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.
A function suitable for use in analyze() with element selection, reformatting, and relabeling performed automatically.
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.
.ungroup_stats
.labels
.formats
s_summary <- function(x) { stopifnot(is.numeric(x)) @@ -379,19 +309,17 @@ ExamplesOn this page - -
make_col_df( tt, colwidths = NULL, @@ -139,54 +85,44 @@ Usage
(ANY) object representing the table-like object to be summarized.
(numeric) internal detail, do not set manually.
(character(1)) The string to display when a column count is NA. Users should not need to set this.
(FormatSpec) The format to be used by default for column counts if one is not specified for an individual column count.
row_paths(x) col_paths(x)
A list of paths to each row/column within x.
cell_values(), fnotes_at_path<-, row_paths_summary(), col_paths_summary()
lyt <- basic_table() %>% split_cols_by("ARM") %>% analyze(c("SEX", "AGE")) @@ -214,19 +153,17 @@ ExamplesOn this page - -
make_split_fun(pre = list(), core_split = NULL, post = list())
(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.
(function or NULL) 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.
do_base_split
(list) zero or more functions which should be called on the list output by splitting.
A custom function that can be used as a split function.
Custom split functions can be thought of as (up to) 3 different types of manipulations of the splitting process:
Pre-processing of the incoming data to be split.
(Row-splitting only) Customization of the core mapping of incoming data to facets.
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 +
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. @@ -193,21 +128,17 @@
spl
labels
custom_split_funs for a more detailed discussion on what custom split functions do.
Other make_custom_split: add_combo_facet(), drop_facet_levels(), make_split_result(), -trim_levels_in_facets()
mysplitfun <- make_split_fun( pre = list(drop_facet_levels), post = list(add_overall_facet("ALL", "All Arms")) @@ -286,19 +217,17 @@ ExamplesOn this page - -
make_split_result( values, datasplit, @@ -148,61 +94,48 @@ Usage
(character or list(SplitValue)) the values associated with each facet.
list(SplitValue)
(list(data.frame)) the facet data for each facet generated in the split.
list(data.frame)
(character) the labels associated with each facet.
(list or NULL) extra values associated with each of the facets which will be passed to analysis functions applied within the facet.
(list) A list of subsetting expressions (e.g., created with quote()) to be used during column subsetting.
quote()
(list) a list representing the result of splitting.
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.
values
datasplit
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.
Other make_custom_split: +
Other make_custom_split: add_combo_facet(), drop_facet_levels(), make_split_fun(), @@ -211,13 +144,11 @@
splres <- make_split_result( values = c("hi", "lo"), datasplit = list(hi = mtcars, lo = mtcars[1:10, ]), @@ -235,19 +166,17 @@ ExamplesOn this page - -
manual_cols(..., .lst = list(...), ccount_format = NULL)
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.
(list) a list of sets of levels, by default populated via list(...).
list(...)
(FormatSpec) the format to use when counts are displayed.
An InstantiatedColumnInfo object, suitable for declaring the column structure for a manually constructed table.
# simple one level column space rows <- lapply(1:5, function(i) { DataRow(rep(i, times = 3)) @@ -198,19 +135,17 @@ ExamplesOn this page - -
# S4 method for class 'VTableTree' matrix_form( obj, @@ -141,54 +87,42 @@ Usage
(flag) if TRUE, the column with the row names in the strings matrix of the output has indented row names (strings pre-fixed).
strings
(flag) 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.
(font_spec) The font that should be used by default when rendering this MatrixPrintForm object, or NULL (the default).
MatrixPrintForm
(numeric(1))] The number of spaces (in the font specified by fontspec) that should be placed between columns when the table is rendered directly to text (e.g., by toString or export_as_txt). Defaults to 3.
3
A list with the following elements:
The content, as it should be printed, of the top-left material, column headers, row labels, and cell values of tt.
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.
nrow_header
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.
get_formatted_cells
library(dplyr) iris2 <- iris %>% @@ -510,19 +441,17 @@ ExamplesOn this page - -
names.Rd
# S4 method for class 'VTableNodeInfo' names(x) @@ -141,43 +86,35 @@ Usage
(TableTree) the object.
The column names of x, as defined in the details above.
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.
no_info.Rd
no_colinfo(obj) # S4 method for class 'VTableNodeInfo' @@ -137,37 +82,30 @@ Usage
TRUE if the object has no/empty instantiated column information, FALSE otherwise.
R/tt_paginate.R
paginate.Rd
pag_tt_indices( tt, lpp = 15, @@ -163,133 +108,107 @@ Usage
(numeric(1)) maximum lines per page including (re)printed header and context rows.
(numeric(1)) minimum sibling rows which must appear on either side of pagination row for a mid-subtable split to be valid. Defaults to 2.
(character) names of sub-tables where page-breaks are not allowed, regardless of other considerations. Defaults to none.
(integer(1), string or NULL) width that title and footer (including footnotes) materials should be word-wrapped to. If NULL, it is set to the current print width of the session (getOption("width")). If set to "auto", the width of the table (plus any table inset) is used. Parameter is ignored if tf_wrap = FALSE.
getOption("width")
"auto"
tf_wrap = FALSE
(numeric(1)) space (in characters) between columns.
(string) name of a page type. See page_types. Ignored when pg_width and pg_height are set directly.
page_types
pg_width
pg_height
(string) name of a font family. An error will be thrown if the family named is not monospaced. Defaults to "Courier".
"Courier"
(numeric(1)) font size. Defaults to 12.
12
(numeric(1)) line height. Defaults to 1.
(flag) whether the dimensions of page_type should be inverted for landscape orientation. Defaults to FALSE, ignored when pg_width and pg_height are set directly.
page_type
(numeric(1)) page width in inches.
(numeric(1)) page height in inches.
(numeric(4)) named numeric vector containing "bottom", "left", "top", and "right" margins in inches. Defaults to .5 inches for both vertical margins and .75 for both horizontal margins.
numeric(4)
"bottom"
"left"
"top"
"right"
.5
.75
(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.
(flag) whether the text for title, subtitles, and footnotes should be wrapped.
pag_tt_indices returns a list of paginated-groups of row-indices of tt.
pag_tt_indices
paginate_table returns the subtables defined by subsetting by the indices defined by pag_tt_indices.
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 @@ -300,82 +219,56 @@
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:
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
Perform 'forced pagination' representing page-by row splits, generating 1 or more tables.
Perform vertical pagination separately on each table generated in (1).
Perform horizontal pagination on the entire table and apply the results to each table page generated in (1)-(2).
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 is performed independently in the vertical and horizontal directions based solely on a pagination data frame, which includes the -following information for each row/column:
Number of lines/characters rendering the row will take after +following information for each row/column:
Number of lines/characters rendering the row will take after word-wrapping (self_extent)
self_extent
The indices (reprint_inds) and number of lines (par_extent) of the rows which act as context for the row
reprint_inds
par_extent
The row's number of siblings and position within its siblings
Given lpp (cpp) is already adjusted for rendered elements which +
Given lpp (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 start = 1.
start = 1
Core Pagination Algorithm:
Initial guess for pagination position is start + lpp (start + cpp)
start + lpp
start + cpp
While the guess is not a valid pagination position, and guess > start, -decrement guess and repeat.
guess > start
An error is thrown if all possible pagination positions between +
While the guess is not a valid pagination position, and guess > start, +decrement guess and repeat.
An error is thrown if all possible pagination positions between start and start + lpp (start + cpp) would be < start after decrementing
start
< start
Retain pagination index
If pagination point was less than NROW(tt) (ncol(tt)), set start to pos + 1, and repeat steps (1) - (4).
NROW(tt)
ncol(tt)
pos + 1
Validating Pagination Position:
Given an (already adjusted) lpp or cpp value, a pagination is invalid if:
The rows/columns on the page would take more than (adjusted) lpp lines/cpp -characters to render including:
word-wrapping
The rows/columns on the page would take more than (adjusted) lpp lines/cpp +characters to render including:
(vertical only) context repetition
(vertical only) footnote messages and/or section divider lines take up too many lines after rendering rows
(vertical only) row is a label or content (row-group summary) row
(vertical only) row at the pagination point has siblings, and it has less than min_siblings preceding or following siblings
min_siblings
pagination would occur within a sub-table listed in nosplitin
nosplitin
s_summary <- function(x) { if (is.numeric(x)) { in_rows( @@ -545,19 +438,17 @@ ExamplesOn this page - -
R/tt_compare_tables.R
prune_table.Rd
prune_table( tt, prune_func = prune_empty_level, @@ -136,49 +81,39 @@ Usage
(function) a function to be called on each subtree which returns TRUE if the entire subtree should be removed.
(numeric(1)) the depth after which subtrees should not be checked for pruning. Defaults to NA which indicates pruning should happen at all levels.
(numeric(1)) used internally, not intended to be set by the end user.
A TableTree pruned via recursive application of prune_func.
prune_func
prune_empty_level() for details on this and several other basic pruning functions included in the rtables package.
adsl <- ex_adsl levels(adsl$SEX) <- c(levels(ex_adsl$SEX), "OTHER") @@ -224,19 +159,17 @@ ExamplesOn this page - -
qtable_layout( data, row_vars = character(), @@ -169,75 +115,61 @@ Usage
(data.frame) the data to tabulate.
(character) the names of variables to be used in row facetting.
(character) the names of variables to be used in column facetting.
(string) the variable to be analyzed. Defaults to the first variable in data.
data
(character or NULL) row label(s) which should be applied to the analysis rows. Length must match the number of rows generated by 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.
(flag) whether each level of nesting should include marginal summary rows. Defaults to FALSE.
(logical(1)) Indicates whether the lowest level of applied to data. NA, the default, indicates that the show_colcounts argument(s) passed to the relevant calls to split_cols_by* @@ -246,36 +178,28 @@
(flag) whether unobserved factor levels should be dropped during facetting. Defaults to TRUE.
additional arguments passed to afun.
(string) this is an implementation detail that should not be set by end users.
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().
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 afun which returns a @@ -290,8 +214,7 @@
qtable(ex_adsl) #> all obs #> (N=400) @@ -442,19 +365,17 @@ ExamplesOn this page - -
rbindl_rtables( x, gap = lifecycle::deprecated(), @@ -140,50 +86,39 @@ Usage
(VTableNodeInfo)TableTree, ElementaryTable, or TableRow object.
VTableNodeInfo
(ANY) elements to be stacked.
(numeric(1)) currently ignored.
When objects are row-bound, 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 formatters::main_title(), formatters::subtitles(), @@ -191,8 +126,7 @@
mtbl <- rtable( header = rheader( rrow(row.name = NULL, rcell("Sepal.Length", colspan = 2), rcell("Petal.Length", colspan = 2)), @@ -243,19 +177,17 @@ ExamplesOn this page - -
rcell( x, format = NULL, @@ -151,100 +97,82 @@ Usage
(ANY) cell value.
(string or function) the format label (string) or formatters function to apply to x. See formatters::list_valid_format_labels() for currently supported format labels.
(string or NULL) label. If non-NULL, it will be looked at when determining row labels.
(flag) whether function is being used in the reference column (i.e. .in_ref_col should be passed to this argument).
(ANY) value to use when in the reference column. Defaults to NULL.
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.
non_ref_rcell
Currently column spanning is only supported for defining header structure.
These objects are imported from other packages. Follow the links below to see their documentation.
export_as_pdf, export_as_txt
lyt <- basic_table() %>% split_cols_by("ARM") %>% analyze(c("AGE", "BMRKR2", "COUNTRY")) @@ -202,19 +146,17 @@ Examples
row_footnotes(obj) row_footnotes(obj) <- value @@ -159,49 +105,39 @@ Usage
row_paths(), col_paths(), row_paths_summary(), col_paths_summary()
# How to add referencial footnotes after having created a table lyt <- basic_table() %>% split_rows_by("SEX", page_by = TRUE) %>% @@ -223,19 +159,17 @@ ExamplesOn this page - -
rheader(..., format = "xx", .lst = NULL)
row specifications, either as character vectors or the output from rrow(), DataRow(), LabelRow(), etc.
A InstantiatedColumnInfo object.
Other compatibility: rrow(), rrowl(), @@ -169,8 +107,7 @@
h1 <- rheader(c("A", "B", "C")) h1 #> An InstantiatedColumnInfo object @@ -196,19 +133,17 @@ ExamplesOn this page - -
rm_all_colcounts(obj) # S4 method for class 'VTableTree' @@ -142,26 +88,20 @@ Usage
obj with all column counts reset to missing
lyt <- basic_table() %>% split_cols_by("ARM") %>% split_cols_by("SEX") %>% @@ -177,19 +117,17 @@ ExamplesOn this page - -
obj_avar(obj) # S4 method for class 'TableRow' @@ -159,42 +105,34 @@ Usage
Various return values depending on the accessor called.
row_paths_summary(x) col_paths_summary(x)
A data frame summarizing the row- or column-structure of x.
ex_adsl_MF <- ex_adsl %>% dplyr::filter(SEX %in% c("M", "F")) lyt <- basic_table() %>% @@ -225,19 +165,17 @@ ExamplesOn this page - -
LabelRow( lev = 1L, label = "", @@ -163,127 +109,104 @@ Usage
(flag) whether the row should be visible (LabelRow only).
(character) internal detail.
additional parameters passed to shared constructor (.tablerow).
.tablerow
A formal object representing a table row of the constructed type.
rrow(row.name = "", ..., format = NULL, indent = 0, inset = 0L)
cell values.
A row object of the context-appropriate type (label or data).
Other compatibility: rheader(), rrowl(), @@ -179,8 +115,7 @@
rrow("ABC", c(1, 2), c(3, 2), format = "xx (xx.%)") #> [DataRow indent_mod 0]: ABC 1 (200%) 3 (200%) rrow("") @@ -189,19 +124,17 @@ ExamplesOn this page - -
rrowl(row.name, ..., format = NULL, indent = 0, inset = 0L)
values in vector/list form.
Other compatibility: rheader(), rrow(), @@ -179,8 +115,7 @@
rrowl("a", c(1, 2, 3), format = "xx") #> [DataRow indent_mod 0]: a 1 2 3 rrowl("a", c(1, 2, 3), c(4, 5, 6), format = "xx") @@ -207,19 +142,17 @@ ExamplesOn this page - -
rtable(header, ..., format = NULL, hsep = default_hsep(), inset = 0L) rtablel(header, ..., format = NULL, hsep = default_hsep(), inset = 0L)
(TableRow, character, or InstantiatedColumnInfo) information defining the header (column structure) of the table. This can be as row objects (legacy), character vectors, or an InstantiatedColumnInfo object.
rows to place in the table.
A formal table object of the appropriate type (ElementaryTable or TableTree).
Other compatibility: rheader(), rrow(), @@ -185,8 +121,7 @@
rtable( header = LETTERS[1:3], rrow("one to three", 1, 2, 3), @@ -334,19 +269,17 @@ ExamplesOn this page - -
Useful links:
https://github.com/insightsengineering/rtables
https://insightsengineering.github.io/rtables/
Report bugs at https://github.com/insightsengineering/rtables/issues
Maintainer: Joe Zhu joe.zhu@roche.com [contributor]
Authors:
Gabriel Becker gabembecker@gmail.com (Original creator of the package)
Adrian Waddell adrian.waddell@gene.com
Other contributors:
Daniel Sabanés Bové daniel.sabanes_bove@roche.com [contributor]
Maximilian Mordig maximilian_oliver.mordig@roche.com [contributor]
Davide Garolini davide.garolini@roche.com [contributor]
Emily de la Rua emily.de_la_rua@contractors.roche.com [contributor]
Abinaya Yogasekaram abinaya.yogasekaram@contractors.roche.com [contributor]
F. Hoffmann-La Roche AG [copyright holder, funder]
simple_analysis(x, ...) # S4 method for class 'numeric' @@ -142,34 +88,25 @@ Usage
(vector) the already split data being tabulated for a particular cell/set of cells.
vector
additional parameters to pass on.
This function has the following behavior given particular types of inputs:
calls mean() on x.
mean()
calls length() on x.
The in_rows() function is called on the resulting value(s). All other classes of input currently lead to an error.
Gabriel Becker and Adrian Waddell
simple_analysis(1:3) #> RowsVerticalSection (in_rows) object print method: #> ---------------------------- @@ -212,19 +146,17 @@ ExamplesOn this page - -
sanitize_table_struct(tt, empty_msg = "-- This Section Contains No Data --")
(string) the string which should be spanned across the inserted empty rows.
If tt is already valid, it is returned unmodified. If tt is degenerate, a modified, non-degenerate version of the table is returned.
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.
empty_msg
Other table structure validation functions: find_degen_struct(), validate_table_struct()
sanitize_table_struct(rtable("cool beans")) #> cool beans #> —————————————————————————————————————— @@ -200,19 +137,17 @@ ExamplesOn this page - -
R/tt_sort.R
score_funs.Rd
cont_n_allcols(tt) cont_n_onecol(j)
(numeric(1)) index of column used for scoring.
A single numeric value indicating score according to the relevant metric for tt, to be used when sorting.
For examples and details, please read the documentation for sort_at_path() and the Sorting and Pruning vignette.
section_div(obj) # S4 method for class 'VTableTree' @@ -194,44 +140,36 @@ Usage
(VTableTree) table object. This can be of any class that inherits from VTableTree or TableRow/LabelRow.
(flag) 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.
section_div<-
(character) 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. See the Details section below for more information.
The section divider string. Each line that does not have a trailing separator will have NA_character_ as section divider.
Assigned value to section divider must be a character vector. If any value is NA_character_ the section divider will be absent for that row or section. When you want to only affect sections or splits, please use only_sep_sections or provide a shorter vector than the number of rows. @@ -245,15 +183,13 @@
only_sep_sections
basic_table() parameter header_section_div and top_level_section_div for global section dividers.
header_section_div
# Data df <- data.frame( cat = c( @@ -338,19 +274,17 @@ ExamplesOn this page - -
sf_args(trim, label, first)
(flag) whether the created split level should be placed first in the levels (TRUE) or last (FALSE, the default).
Other conventions: compat_args(), constr_args(), @@ -168,19 +106,17 @@
sort_at_path( tt, path, @@ -137,58 +83,47 @@ Usage
(function) 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.
VTableRow
(flag) 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.
scorefun
(string) 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.
"omit"
"last"
"first"
(character) internal detail, do not set manually.
A TableTree with the same structure as tt with the exception that the requested sorting has been done at path.
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 @@ -212,9 +147,7 @@
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 DataRows. Here, some -useful descriptor and accessor functions (coming from related vignette):
DataRow
cell_values() - Retrieves a named list of a TableRow or TableTree object's values.
formatters::obj_name() - Retrieves the name of an object. Note this can differ from the label that is displayed (if any is) when printing.
formatters::obj_name()
formatters::obj_label() - Retrieves the display label of an object. Note this can differ from the name that @@ -222,23 +155,18 @@
formatters::obj_label()
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).
Score functions cont_n_allcols() and cont_n_onecol().
formatters::make_row_df() and table_structure() for pathing information.
tt_at_path() to select a table's (sub)structure at a given path.
# Creating a table to sort # Function that gives two statistics per table-tree "leaf" @@ -346,19 +274,17 @@ ExamplesOn this page - -
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:
The name of the split (often the variable being split).
Current column split values. This is recovered from the current column path.
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 @@ -191,19 +134,17 @@
all_cols_n
cur_col_n
spl_context_to_disp_path(ctx)
(data.frame) the spl_context data frame where the error occurred.
A character string containing a description of the row path corresponding to ctx.
ctx
spl_variable(spl) # S4 method for class 'VarLevelSplit' @@ -151,42 +97,34 @@ Usage
(VarLevelSplit) the split object.
For splits with a single variable associated with them, returns the split. Otherwise, an error is raised.
split_cols_by( lyt, var, @@ -143,100 +89,81 @@ Usage
(string or NULL) level of var that should be considered ref_group/reference.
lyt <- basic_table() %>% split_cols_by("ARM") %>% analyze(c("AGE", "BMRKR2")) @@ -473,19 +395,17 @@ ExamplesOn this page - -
split_cols_by_multivar( lyt, vars, @@ -146,85 +92,69 @@ Usage
library(dplyr) ANL <- DM %>% mutate(value = rnorm(n()), pctdiff = runif(n())) @@ -269,19 +199,17 @@ ExamplesOn this page - -
keep_split_levels(only, reorder = TRUE) remove_split_levels(excl) @@ -155,99 +101,80 @@ Usage
(character) levels to retain (all others will be dropped). If none of the levels is present an empty table is returned.
(flag) whether the order of only should be used as the order of the children of the split. Defaults to TRUE.
only
(character) levels to be excluded (they will not be reflected in the resulting table structure regardless of presence in the data).
(ANY) for internal use only.
(character) labels to use for the remaining levels instead of the existing ones.
(character) new order of factor levels. All need to be present in the data. To add empty levels, rely on pre-processing or create your custom_split_funs.
(character) labels for (new order of) factor levels. If named, the levels are matched. Otherwise, the order of neworder is used.
neworder
(flag) whether levels that are not in neworder should be dropped. Default is TRUE. Note: drlevels = TRUE does not drop levels that are not originally in the data. Rely on pre-processing or use a combination of split functions with make_split_fun() to also drop unused levels.
drlevels = TRUE
(string) variable whose factor levels should be trimmed (e.g. empty levels dropped) separately within each grouping defined at this point in the structure.
(flag) whether empty levels in the variable being split on (i.e. the "outer" variable, not innervar) should be dropped. Defaults to TRUE.
innervar
A function that can be used to split the data accordingly. The actual function signature is similar to the one you can define when creating a fully custom one. For more details see custom_split_funs.
keep_split_levels(): keeps only specified levels (only) in the split variable. If any of the specified +
keep_split_levels(): keeps only specified levels (only) in the split variable. If any of the specified levels is not present, an error is returned. reorder = TRUE (the default) orders the split levels according to the order of only.
reorder = TRUE
remove_split_levels(): Removes specified levels (excl) from the split variable. Nothing done if not in data.
excl
The following parameters are also documented here but they are only the default signature of a split function: df (data to be split), spl (split object), and vals = NULL, labels = NULL, trim = FALSE (last three only for internal use). See custom_split_funs for more details and make_split_fun() for a more advanced API.
vals = NULL
labels = NULL
trim = FALSE
custom_split_funs, add_overall_level(), add_combo_levels(), and trim_levels_to_map().
# keep_split_levels keeps specified levels (reorder = TRUE by default) lyt <- basic_table() %>% split_rows_by("COUNTRY", @@ -417,19 +340,17 @@ ExamplesOn this page - -
split_rows_by( lyt, var, @@ -145,120 +91,98 @@ Usage
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.
labels_var
lyt <- basic_table() %>% split_cols_by("ARM") %>% split_rows_by("RACE", split_fun = drop_split_levels) %>% @@ -412,19 +331,17 @@ ExamplesOn this page - -
split_rows_by_multivar( lyt, vars, @@ -146,99 +92,81 @@ Usage
split_rows_by() for typical row splitting, and split_cols_by_multivar() to perform the same type of split on a column basis.
lyt <- basic_table() %>% split_cols_by("ARM") %>% split_rows_by_multivar(c("SEX", "STRATA1")) %>% @@ -270,19 +198,17 @@ ExamplesOn this page - -
summarize_row_groups( lyt, var = "", @@ -139,70 +85,57 @@ Usage
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 @@ -215,14 +148,12 @@
xx
DM2 <- subset(DM, COUNTRY %in% c("USA", "CAN", "CHN")) lyt <- basic_table() %>% @@ -344,19 +275,17 @@ ExamplesOn this page - -
R/00tabletrees.R
tabclasses.Rd
ElementaryTable( kids = list(), name = "", @@ -182,166 +127,137 @@ Usage
(data.frame) currently stored but otherwise ignored.
A formal object representing a populated table.
table_shell( tt, widths = NULL, @@ -149,67 +95,53 @@ Usage
(numeric or NULL) Proposed widths for the columns of x. The expected length of this numeric vector can be retrieved with ncol(x) + 1 as the column of row names must also be considered.
ncol(x) + 1
(string) character to repeat to create header/body separator line. If NULL, the object value will be used. If " ", an empty separator will be printed. See default_hsep() for more information.
default_hsep()
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.
table_shell_str
value_formats() for a matrix of formats for each cell in a table.
library(dplyr) iris2 <- iris %>% @@ -244,19 +176,17 @@ ExamplesOn this page - -
table_structure(x, detail = c("subtable", "row"))
(string) either row or subtable.
row
subtable
No return value. Called for the side-effect of printing a row- or subtable-structure summary of x.
library(dplyr) iris2 <- iris %>% @@ -276,19 +215,17 @@ ExamplesOn this page - -
top_left(obj) # S4 method for class 'VTableTree' @@ -156,43 +102,35 @@ Usage
A character vector representing the top-left material of obj (or obj after modification, in the case of the setter).
# S4 method for class 'VTableTree' toString( x, @@ -156,88 +102,72 @@ Usage
(ANY) object to be prepared for rendering.
(logical(1)) should truetype (non-monospace) fonts be allowed via fontspec. Defaults to FALSE. This parameter is primarily for internal testing and generally should not be set by end users.
A string representation of x as it appears when printed.
Manual insertion of newlines is not supported when 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.
tf_wrap = TRUE
wrap_string()
library(dplyr) iris2 <- iris %>% @@ -273,19 +203,17 @@ ExamplesOn this page - -
tree_children(x) tree_children(x) <- value
(TableTree or ElementaryTable) an object with a tree structure.
(list) new list of children.
A list of direct children of x.
trim_levels_in_facets(innervar)
(character) the variable(s) to trim (remove unobserved levels) independently within each facet.
A function suitable for use in the pre (list) argument of make_split_fun.
pre
Other make_custom_split: add_combo_facet(), drop_facet_levels(), make_split_fun(), -make_split_result()
trim_levels_to_map(map = NULL)
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.
A function that can be used as a split function.
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_in_group().
map <- data.frame( LBCAT = c("CHEMISTRY", "CHEMISTRY", "CHEMISTRY", "IMMUNOLOGY"), PARAMCD = c("ALT", "CRP", "CRP", "IGA"), @@ -191,19 +129,17 @@ ExamplesOn this page - -
all_zero_or_na(tr) all_zero(tr) @@ -140,58 +86,45 @@ Usage
(function) function which takes a TableRow object and returns TRUE if that row should be removed. Defaults to all_zero_or_na().
(numeric(1)) (used by low_obs_pruner only). Minimum aggregate count value. Subtables whose combined/average count are below this threshold will be pruned.
low_obs_pruner
(string) how count values should be aggregated. Must be "sum" (the default) or "mean".
"sum"
"mean"
A logical value indicating whether tr should be included (TRUE) or pruned (FALSE) during pruning.
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.
all_zero_or_na
NaN
0
Inf
-Inf
all_zero returns TRUE for any non-LabelRow which contains only (non-missing) zero values.
all_zero
content_all_zeros_nas prunes a subtable if both of the following are true:
content_all_zeros_nas
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).
prune_empty_level combines all_zero_or_na behavior for TableRow objects, content_all_zeros_nas on +
prune_empty_level
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.
content_table(tt)
prune_zeros_only behaves as prune_empty_level does, except that like all_zero it prunes @@ -201,14 +134,12 @@
prune_zeros_only
prune_table(), trim_rows()
adsl <- ex_adsl levels(adsl$SEX) <- c(levels(ex_adsl$SEX), "OTHER") adsl$AGE[adsl$SEX == "UNDIFFERENTIATED"] <- 0 @@ -388,19 +319,17 @@ ExamplesOn this page - -
trim_rows(tt, criteria = all_zero_or_na)
The table with rows that have only NA or 0 cell values removed.
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.
Visible LabelRows 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.
criteria
adsl <- ex_adsl levels(adsl$SEX) <- c(levels(ex_adsl$SEX), "OTHER") @@ -257,19 +193,17 @@ ExamplesOn this page - -
export_as_tsv( tt, file = NULL, @@ -142,84 +88,67 @@ Usage
(string) the path of the file to written to or read from.
(string) defaults to \t. See utils::write.table() for more details.
\t
utils::write.table()
(any) additional arguments to be passed to utils::write.table().
any
export_as_tsv returns NULL silently.
import_from_tsv returns a data.frame with re-constituted list values.
import_from_tsv
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 "|".
value_func
"|"
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.
path_enriched_df() for the underlying function that does the work.
tt_at_path(tt, path, ...) tt_at_path(tt, path, ...) <- value
unused.
Setting NULL at a defined path removes the corresponding sub-table.
# Accessing sub table. lyt <- basic_table() %>% split_cols_by("ARM") %>% @@ -235,19 +172,17 @@ ExamplesOn this page - -
update_ref_indexing(tt)
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.
In the future this should not generally need to be called manually.
A TableTree (rtables-built table) is considered degenerate if:
It contains no subtables or data rows (content rows do not count).
It contains a subtable which is degenerate by the criterion above.
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
warn_only
validate_table_struct(tt) assert_valid_table(tt, warn_only = FALSE)
(flag) whether a warning should be thrown instead of an error. Defaults to FALSE.
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.
This function is experimental and the exact text of the warning/error is subject to change in future releases.
Other table structure validation functions: find_degen_struct(), sanitize_table_struct()
validate_table_struct(rtable("hahaha")) #> [1] FALSE if (FALSE) { # \dontrun{ @@ -209,19 +141,17 @@ ExamplesOn this page - -
value_formats(obj, default = obj_format(obj)) # S4 method for class 'ANY' @@ -142,37 +88,29 @@ Usage
(VTableTree or TableRow) a table or row object.
(string, function, or list) default format.
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).
table_shell() and table_shell_str() for information on the table format structure.
lyt <- basic_table() %>% split_rows_by("RACE", split_fun = keep_split_levels(c("ASIAN", "WHITE"))) %>% analyze("AGE") @@ -188,19 +126,17 @@ ExamplesOn this page - -
split_cols_by_cuts( lyt, var, @@ -210,143 +156,118 @@ Usage
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.
library(dplyr) # split_cols_by_cuts @@ -512,19 +433,17 @@ ExamplesOn this page - -
vars_in_layout(lyt) # S4 method for class 'PreDataTableLayouts' @@ -148,48 +94,35 @@ Usage
(PreDataTableLayouts) the layout (or a component thereof).
A character vector containing the unique variables explicitly used in the layout (see the notes below).
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:
Variable being split on (directly or via cuts)
Element of a Multi-variable column split
Content variable
Value-label variable
This function will not detect dependencies implicit in analysis or summary functions which accept x +
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.
lyt <- basic_table() %>% split_cols_by("ARM") %>% split_cols_by("SEX") %>% @@ -207,19 +140,17 @@ ExamplesOn this page - -
<\/p> #> <\/div> #>
