restrict_facets function factory for use with make_split_funmake_subset_expr for use when constructing custom splitting behaviorround_type instead of needing to specify on export #1040obj_round_type getter and setter methods.pkgdown siteparent_name argument to split_rows_by* and analyze* functions to manually control names of (and thus paths to) the subtables created. #1024 by @gmbeckertt_row_path_exists, which determines whether a path exists within a table's row structure, optionally restricted to resolving to a particular type of node (row, table, elementary table). #1024 by @gmbeckertt_normalize_row_path which resolves a path including the "*" wild card to all existing paths within a table, optionally restricted to resolving to a particular type. #1024 by @gmbecker?pathing) to the man page for the above functions.pathing vignette. @gmbeckermake_row_df is called on a VTableTree the returned df now includes new sect_div_from_path and self_section_div columns. #1024 by @gmbeckersection_div_info convenience function which returns portions of make_row_df's result relevant to section dividers. #1024 by @gmbeckersection_div_at_path and section_div_at_path<- for getting and setting section dividers for substructures within the table. The latter supports "*" wildcards for flexible usage. #1024 by @gmbecker?section_div) updated and expanded. #1024 by @gmbeckeras_result_df to "de-uniqify" names that were altered for pathability when determining group values in the result dataframe/ard. #1024 by @gmbeckersection_div<- with only_sep_sections = TRUE more values than levels of nesting present is now more informative, and occurs regardless of whether only_sep_sections was set manually or automatically (length(value) < nrow(tt)). #1024 by @gmbeckersection_div<- now works correctly on tables that include top level siblings in their row structure (e.g., when unnested structure is added via nested = FALSE or adding a row splitting after an analyze call). #1024 by @gmbeckersection_div<- with only_sep_sections = FALSE is now consistent regarding which value is set when analyze calls occur at different levels of nesting within the corresponding layout, particularly as top-level non-nested siblings. #1024 by @gmbeckersection_div<- no longer sets a section div on non-visible label rows when setting a section divider for a content row on the same group. #1024 by @gmbeckersection_div<- when given a full-length (nrow(tt)) vector now sets 'section dividers' on label rows and content rows correctly when both are visible for the same facet. #1024 by @gmbecker[ methods with signatures involving character and missing. @gmbecker[ methods to gracefully handle new sibling name de-duplication scheme. @gmbeckersubset_cols generic and methods are now exported.has_force_pag generic and methods are now exported.stat_string to as_result_df(make_ard = TRUE) to preserve the original string representation of the statistics.add_tbl_name_split to as_result_df() to handle split levels constituted by different table names..alt_df_full which will always be the full alt_counts_df data.frame.sort_at_path or prune_table, score functions can also accept decreasing to receive sort order.split_cols_by_multivar() when having more than one value. Now as_result_df(make_ard = TRUE) adds a predefined split name for each of the multivar splits.tt_at_path() caused by the impossibility to solve multiple branches with identical names.as_result_df(make_ard = TRUE) uses the cell values for stat_strings for these exceptions.section_div argument to analyze no longer sometimes applies dividers between each generated row in some cases. by @gmbecker[<- causing information to be stripped from other cells if a new rcell is set within a table row.as_result_df(make_ard = TRUE) when different columns had different amounts of "" values.stat_name is character(0) (as_result_df(make_ard = TRUE)).integer(), i.e. producing an empty table.add_tbl_str_decimals = TRUE to ... into as_result_df(make_ard = TRUE) to add stat_string column for the
ARD output.stat_string are more fragile than default as_result_df(make_ard = TRUE) calculation and are in theory optional, a warning is thrown when errors arise and the stat_string column is not added.tt_at_path used a path based on row labels instead of row names.keep_split_levels() is used to keep absent values.[.keep_split_levels() when branch is empty (character(0)).as_result_df().make_ard output for single-line statistical outputs.stat_names to rcell() to be used by as_result_df(make_ard = TRUE).docx document generation to the new package rtables.officer.as_result_df() parameters as_strings and as_viewer into data_format = c("full_precision", "strings", "numeric") following the same outputs.as_result_df() to have a standard behavior, with all the relevant parameters, and a possibility to add personalized spec.result_df_specs(), because as_result_df() was a too shallow wrapper.as_result_df() parameters as_is and simplify parameters to remove structural information.flextable from a TableTree object.analyze that was causing an error when passing a single NA value to the
var_labels parameter.analyze calls in as_result_df.section_properties_default() function to define standard portrait properties for tables..html outputs.bold_titles to tt_to_flextable() to bold titles.tt_to_flextable(), and/or extend themes.reorder_split_levels() to cover more edge cases and be more stringent in the allowed inputs.tt input from theme_docx_default() and added code to handle row classes and number of columns internally.theme_docx_default().bold_titles to tt_to_flextable() to bold titles."\n" newline issues in as_html by relying onto output devices for newline handling. Added expand_newlines = FALSE default to allow previous behavior.keep_split_levels() throws now an error if the user requests to keep levels that are not present in data.tt_as_flextable() header when title was added.flextable."" having larger imposed margins than filled cell. They are transformed into " " before rendering.theme_docx_default() when only one line of column names is present, but top left information is on multiple lines.sep = "\t" and set other parameters via ... parameter propagation in export_as_tsv.matrix_form and toString.simple_analysis into utils file.theme_docx_default() showing how to extend the default theme.theme_html_default().col_counts vignette wording, as CRAN macOS check failed. Raised the issue with the R-core team already.truetype fonts based on formatters version >= 0.5.8. Nearly all functions related to pagination or export now accept fontspec argument and pass it around accordingly, by @gmbecker.make_split_fun provided that core_split associates the generated facets with subsetting expressions. Subsetting expressions remain unnecessary for splits in row space. By @gmbecker.make_split_res, add_to_split_result now accept a list of subsetting expressions which will be attached to the values, by @gmbecker.value_expr internal getter and setter methods, by @gmbecker.split_cols_by* functions now accept show_colcounts and colcount_format arguments.colcount_visible getter and setter for changing column count visibility in an already built table @gmbecker.facet_colcount getter and setter column count value at arbitrary point in column structure of built table @gmbecker.facet_colcounts_visible setter to conveniently set the column count visibility of a set of sibling facets in column spacerm_all_colcounts convenience function for turning off visibility all column counts throughout the column structure @gmbecker.as_html preventing indentation from being applied in Viewer output.col_counts<- and col_total<- methods now explicitly convert value to integer, by @gmbecker.col_gap is now respected in nlines row methods, and thus by make_row_df, by @gmbecker.lifecycle badge files for deprecated documentation.gap and check_headers arguments to rbindl_rtables using lifecycle.top_level_section_div for basic_table to set section dividers for top level rows.keep_label_rows to as_result_df to have these lines visible.sort_at_path now gives informative error messages when the given path does not exist.rlistings decoration (e.g. titles and footers) expansion when there are new lines. Moved relevant handling from rtables' matrix_form function to formatters' dedicated mform_handle_newlines function.rtables_root not being removed when using as_result_df.as_result_df where rows of the table have only "root" as path index.sort_at_path pathing to ignore leading "root" element (regardless of actual root element name) to match current tt_at_path behavior.section_div for analysis of multiple variables (AnalyzeMultiVars).mf_rinfo(mf)) and actual selected indentation from matrix_form(mf, indent_rownames = FALSE).as_html preventing indentation from being applied in Viewer output.col_counts<- and col_total<- methods now explicitly convert value to integer, by @gmbecker.col_gap is now respected in nlines row methods, and thus by make_row_df, by @gmbecker.as_html to accommodate \n characters.add_analyzed_var and trim_zero_rows.ref_group reordering in column splits so not to change the order.bold argument to as_html to bold specified elements, and header_sep_line
argument to print a horizontal line under the table header in rendered HTML output.section_div and section_div<-). They also accept
split section structure assignment.header_section_div setters and getters for layout and table objects along with
related basic_table parameter.na_str argument to analyze_colvars to set custom string to print in place of missing values.data.frame outputs for as_result_df() via flag parameters as_viewer, as_strings, and
expand_colnames.export_as_pdf function to formatters.as_result_df causing misalignment of column names.row_paths() was giving a different path due to it being made of
named values.as_result_df when called on tables with less than 3 rows.styler and resolved package lint. Changed default indentation from 4 spaces to 2.as_html.col_fnotes_here to be replaced with col_footnotes.section_div methods now have a dedicated documentation page that is visible to users.txt, they preserve the horizontal separator of the table.stringi and checkmate as they are fundamental packages for string handling and
argument checking.formatters.na_str).Viewer and as_html to fail when new line characters were added..docx exports with export_as_docx().flextable customization with theme function specific for word documents (theme_docx_default()).NA rows to be included in every .df_row split.cfun/afun) can use new parameters to extend analysis calculations: .alt_df_row and .alt_df give access to alt_counts_df across columns, while .all_col_exprs and .all_col_counts contains global information about all columns.rbind will retain titles/footer information if identical in all objects or only present in the first object being bound.cfun/afun) have more information about current column split; .spl_context has access to cur_col_id, cur_col_expr, cur_col_split, and cur_col_split_val.qtable.qtable_layout from qtable.qtable labeling via row_labels (#698).alt_counts_df presents different splits from df.formatters: formatters::check_aligns superseded internal function chk_rtables_align and formatters::list_valid_aligns superseded rtables_aligns.page_by machinery caused by migration to formatters 0.5.1 pagination framework.page_by labels become missing when only one level exist in the split_rows_by.var levels but not lblvar levels.qtable function to create a table with a single top-level structure in both row and column dimensions involving faceting by 0 or more variables in each.as_result_df function to flatten a table into a dataframe.sanitize_table_struct, validate_table_struct, find_degen_struct to support degenerative table rendering.paginate_table) by generalizing parameters' defaults (cpp, lpp, and font_size).export_as_txt to formatters. Added to reexports.export_as_rtf to formatters. Not re-exported.r2rtf to Suggestsformatters and is now invoked from there. paginate_table remains as a convenience function.str method when called upon table objects.str method for VTableTree objects with a default max.level of 3, as the infinite default from base is not
useful or informative.font_size value is now 8 across pagination and export machinerymargins argument in pagination and export machinery now (correctly) interpreted as inches. This change is inherited from formatterslpp and cpp now default to NA_integer_, which is interpreted as inferring their value from the physical page size specified."letter". Pagination can still be turned off in either direction by setting l/cpp to NULL explicitly.symbol and an index. Messages associated with symbols will only appear once per page in the footer materials regardless of number of elements referenced in the page with that symbol. Matches and inherits from changes in formatterstrim_zero_rows.cell_values after sorting.vpaginate_table.sort_at_path.split_label to function split_rows_by_multivar and extra_args to function split_cols_by_multivar.split_rows_by_multivar documentation.make_split_fun function for creation of custom split functionsbasic_table now accepts colcount_formatspl_context now includes root row in row-split contexts.export_as_pdf now correctly takes margins into account when calculating lpp and cpp from page size.colwidths values correctlynlines TableRow method (used for both rows and column label extent in pagination) now correctly handles column spanningverbose = TRUE now includes original and adjusted lines-per page informationcont_n_allcols and cont_n_onecol score functions now throw errors when they are applied to subtables that
have no content table, instead of the previously returned NAsort_at_path now emits an informative error message when score functions fail.paginate_table now accepts colwidths and paginates assuming column label and
cell values are wrapped to those widths.make_row_df now accepts colwidths and calculates row extents assuming cell values
are wrapped to those widthsnlines TableRow method now uses provided colwidths to assume cell-value wrappingexport_to_txt now automatically paginates when any form of page dimension is provided
(previously the default was unconditionally not paginating).formatters increased to >=0.4.0[<- now treats character i and j values as paths, the same as [ always has.[<- CellValue method now preserves CellValue attributes (e.g., format)nlines methods now accept both colwidths and max_widthmax_width is now used during pagination to determine lines taken up by referential footnotesmake_col_df now accepts colwidths argument, and can be called directly on InstantiatedColumnInfo objectsformatters increase to >0.3.3.12"" values.formatters increase to >0.3.3.11paginate_table now accepts tf_wrap and max_width and respects title/footer word wrapping when presenttf_wrap and max_width and use them in both pagination (when turned on) and toString when used (pdf, txt exporters).formatters increased to >0.3.3.10export_as_pdf now accepts standard page/font size parameterswidth, height, fontsize are soft deprecated (no warning) and
will be fully deprecated and then removed in the future.toString method for VTableTree now accepts tf_wrap and max_widthexport_as_txt and export_as_pdf now accept cpp, as well as tf_wrap and max_width and
default to tf_wrap being on and max_width = cpp when cpp is non-NULL.basic_table now accepts inset argument for declaring table insettable_inset slot, with accessor functions.matrix_form method for VTableTree sets table_inset valueformatters to >0.3.3.5 for table_inset supportexact=TRUE in all calls to attr within access functionsformatters to >0.3.3.4na_str argument, which specifies na string with the same
inheritance rules as formatsna_str informationformatters to >= 0.3.3.3 for support of na_strs with NA_character_ valuespaginate_table now takes page dimension and font information and uses formatters::page_lcpp to
calculate lpp and cpp automatically when those are provided.formatters to >= 0.3.3.2 for page_lcpppaginate_table now accepts cpp and will perform vertical pagination when it is non-nullvpaginate_table is now deprecatedformatters to >=0.3.2.4section_div argument in split_rows_by* function)formatters to >=0.3.2.3add_combo_levels #340) no longer block rbindingcol_counts getter and setter now accept path argument.cbinding tables from working correctly ([#324]](https://github.com/insightsengineering/rtables/issues/324))linesep argument to toString and related functions renamed to hsepformatters to >=0.3.0hsep argument to build_table which sets the horizontal separator for the constructed table (and subtables thereof)horizontal_sep and horizontal_sep<- accessors for constructed tables, the latter of which is mandatorily recursive.split_rows_by(var, child_labels="hidden") no longer removes the structural subtable corresponding to levels of var (#314)formatable dependency renamed to formatters for suitability of release to CRANformatters (previously formatable) to >=0.2.0cfun caused error (#307)path_enriched_df (which powers tsv export), related to (#308)table_shell to display shell of table with formatslinesep argument to toString to specify a character to create the line separator. Previously we used the en dash as the line separator character, now we changed the default to the em dash reducing the gap between the dash line elements.NULL is now deprecatedinsert_rrow is deprecated in favor of new insert_row_at_path and label_at_path<- functions.spl_context optional argumenttrim_levels_to_map split function for dictating exact combinations of values which should appear across splitsvalue_formats function now exported which returns/displays the effective formats of all cells in a tablecompare_rtables is now much faster for tables with many cellscompare_rtables now accepts structure argument which adds comparison of structure (by way of row- and column-path positions)tt_to_flextable coercion functionexport_as_pdf exporter functionvalue_at and cell_values functions now have methods for TableRow objects making them usable in sorting/pruning functionstrim_levels_to_map split function based on [@wwojciech](https://github.com/wwojciech)'s work in #203fnotes_at_path<- functiontrim_levels_in_group now trims empty levels of outer (split) variable by defaultvalue_at and cell_values now work for tablerow objectsas_html bug in multivar split columns caseas_html refactored to support newlines while respecting table structuredf returned by make_row_df now reflects extent in lines, thus will return larger values if the row-label or any cell values contain newlines.as_html (or viewed in Viewer) were missing the table class attribute (#194)DataRow with incorrect number of columns is now an error (#199)colspan case.NEWS.md filevars_in_layout to list (explicitly named only) variables used in a layoutSynchronize release with GitHub commit sha.
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.
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 now force()s all customization arguments immediately, which prevents problems when called within loop/lapply constructs.multivar column splitsanalyze_colvars's inclNAs argument now respected.make_pagdfmake_pagdf indent calculation remains correct.in_ref_col and .ref_group work correctly when custom splitting is used (including the provided combination-levels mechanism)multivar case (split itself now has default name "multivars")MultiVarSplit with different associated levelssplit_cols_by_multivarcbinds.summarize_row_groups can now accept a list of functions for the cfun argument as analyze_colvars does.value_formats accessor so it operates on CellValues rather than the raw contained values (thus always returning NULL)rrow constructor no longer interprets cell formats a row format when they are the same across all cells. Fixes bug in "correct way" code discussed in #112in_rows as cell formats rather than row formats.cbind_rtables can now take more than 2 tables.analyze_colvarsanalyze_colvars now takes and adheres to inclNAs argumentxx.xx (xx.xx - xx.xx) and x.xxxx | (<0.0001)col_by in rtabulate now accepts matrices:
col_by_to_matrix, col_by_to_factor, by_factor_to_matrix.by_add_total, by_all, by_combine, by_quartile, by_compare_subset, by_hierarchical, by_drop_empty_cols.New utility functions to deal with variable labels:
label, var_labels<-, var_labels, var_labels_remove, var_relabel, with_label.Other new functions:
cbing_rtables.empty_rtables, is_empty_rtable, is_non_empty_rtable, is_rtable.header_indent, header_indent<-, header_row.names, header_row.names<-.insert_rrow.rbind.rtable now supports binding rtables with rows, e.g. rbind(tbl1, rrow(), tbl2) or rbind(tbl1, rrow("row name"), tbl2).rbindl_rtables supports NULL objects in the list (except for the first element).indent function.header_add_N deals gracefully with NULL objects.rtablulate family of functions do not support the row_*_data_args arguments anymore. Instead, the col_wise_args argument is introduced.order_rrows, sort_rrows, order_rtables, and sort_rtables are introduced.rtables from being unlisted with unlist.rtables.Viewer now also accepts objects of class shiny.tag (defined in package htmltools).as.html accepts class.table, class.tr, class.th, and class.td as an argument.sprintf_format for formatting rcells (thanks to Doug Kelkhoff for the suggestion)."(N=xx)" and ">999.9" format labels.rtabulate has now an argument col_N and the function col_N().0.1.0 is a major re-design with lots of internal refactoring and the following API changes:
rtable has now header argument instead of col.names. A header can be created with rheader and is a collection of rrows. If header is set to c("A", "B") then rtable will create the rheader with a single rrow and by setting row.name to NULL.header and header<- function added.get_rcell_formats to list_rcell_format_labels.rcell format is NULL then the cell content will be converted to a string with paste(as.character(x), collapse = ', ').[i,] works now to subset a table.rbind method for rtables.row.names<-.rtable method.rtabulate added for creating tables.indented_row.names function added.