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
🙏 Thank you for taking the time to contribute!
Your input is deeply valued, whether an issue, a pull request, or even feedback, regardless of size, content or scope.
👶 Getting started
📔 Code of Conduct
🗃 License
Please refer the project documentation for a brief introduction. Please also see other articles within the project documentation for additional information.
A Code of Conduct governs this project. Participants and contributors are expected to follow the rules outlined therein.
All your contributions will be covered by this project’s license.
We use GitHub to track issues, feature requests, and bugs. Before submitting a new issue, please check if the issue has already been reported. If the issue already exists, please upvote the existing issue 👍.
For new feature requests, please elaborate on the context and the benefit the feature will have for users, developers, or other relevant personas.
This repository uses the GitHub Flow model for collaboration. To submit a pull request:
Create a branch
Please see the branch naming convention below. If you don’t have write access to this repository, please fork it.
Make changes
Make sure your code
Create a pull request (PR)
In the pull request description, please link the relevant issue (if any), provide a detailed description of the change, and include any assumptions.
Suppose your changes are related to a current issue in the current project; please name your branch as follows: <issue_id>_<short_description>. Please use underscore (_) as a delimiter for word separation. For example, 420_fix_ui_bug would be a suitable branch name if your change is resolving and UI-related bug reported in issue number 420 in the current project.
<issue_id>_<short_description>
_
420_fix_ui_bug
420
If your change affects multiple repositories, please name your branches as follows: <issue_id>_<issue_repo>_<short description>. For example, 69_awesomeproject_fix_spelling_error would reference issue 69 reported in project awesomeproject and aims to resolve one or more spelling errors in multiple (likely related) repositories.
<issue_id>_<issue_repo>_<short description>
69_awesomeproject_fix_spelling_error
69
awesomeproject
monorepo
staged.dependencies
Sometimes you might need to change upstream dependent package(s) to be able to submit a meaningful change. We are using staged.dependencies functionality to simulate a monorepo behavior. The dependency configuration is already specified in this project’s staged_dependencies.yaml file. You need to name the feature branches appropriately. This is the only exception from the branch naming convention described above.
staged_dependencies.yaml
Please refer to the staged.dependencies package documentation for more details.
This repository follows some unified processes and standards adopted by its maintainers to ensure software development is carried out consistently within teams and cohesively across other repositories.
This repository follows the standard tidyverse style guide and uses lintr for lint checks. Customized lint configurations are available in this repository’s .lintr file.
tidyverse
lintr
.lintr
Lightweight is the right weight. This repository follows tinyverse recommedations of limiting dependencies to minimum.
If the code is not compatible with all (!) historical versions of a given dependenct package, it is required to specify minimal version in the DESCRIPTION file. In particular: if the development version requires (imports) the development version of another package - it is required to put abc (>= 1.2.3.9000).
DESCRIPTION
abc (>= 1.2.3.9000)
We continuously test our packages against the newest R version along with the most recent dependencies from CRAN and BioConductor. We recommend that your working environment is also set up in the same way. You can find the details about the R version and packages used in the R CMD check GitHub Action execution log - there is a step that prints out the R sessionInfo().
R CMD check
sessionInfo()
If you discover bugs on older R versions or with an older set of dependencies, please create the relevant bug reports.
pre-commit
We highly recommend that you use the pre-commit tool combined with R hooks for pre-commit to execute some of the checks before committing and pushing your changes.
R hooks for pre-commit
Pre-commit hooks are already available in this repository’s .pre-commit-config.yaml file.
.pre-commit-config.yaml
As mentioned previously, all contributions are deeply valued and appreciated. While all contribution data is available as part of the repository insights, to recognize a significant contribution and hence add the contributor to the package authors list, the following rules are enforced:
git blame
*Excluding auto-generated code, including but not limited to roxygen comments or renv.lock files.
roxygen
renv.lock
The package maintainer also reserves the right to adjust the criteria to recognize contributions.
If you have further questions regarding the contribution guidelines, please contact the package/repository maintainer.
vignettes/formatters.Rmd
formatters.Rmd
Gabriel Becker. Author. original creator of the package
F. Hoffmann-La Roche AG. Copyright holder, funder.
Becker G, Waddell A (2024). formatters: ASCII Formatting for Values and Tables. -R package version 0.5.9.9005, +R package version 0.5.9.9006, https://github.com/insightsengineering/formatters/, https://insightsengineering.github.io/formatters/.
@Manual{, title = {formatters: ASCII Formatting for Values and Tables}, author = {Gabriel Becker and Adrian Waddell}, year = {2024}, - note = {R package version 0.5.9.9005, + note = {R package version 0.5.9.9006, https://github.com/insightsengineering/formatters/}, url = {https://insightsengineering.github.io/formatters/}, }
mf_update_cinfo
export_as_txt
mform_handle_newlines
CRAN release: 2024-09-12
format_value
NA
na_str
CRAN release: 2024-06-19
TrueType
col_gap
lifecycle
width
height
fontsize
export_as_pdf()
CRAN release: 2024-04-15
\r
rlistings
insightsengineering/rlistings#155
max_width
.handle_max_width
toString
min_siblings > 0
matrix_print_form
MatrixPrintForm
CRAN release: 2023-12-06
styler
set_default_hsep()
getOption("formatters_default_hsep")
export_as_pdf
rtables
paginate_to_mpfs
font_lcpi
wrap_string
stringi::stri_wrap
paginate_to_mpfs()
cpp
lpp
CRAN release: 2023-08-25
decimal
dec_right
dec_left
rep_cols
list_valid_aligns()
align
NULL
fmt_config
prov_footer
1
insightsengineering/rtables#705
page_by
getter
setter
obj_align
obj_align<-
format
center
"NA"
CRAN release: 2023-05-25
MPF
insightsengineering/rtables#634
font_size
NA_integer_
hexSticker
CRAN release: 2023-03-02
widths
colwidths
na
obj_na_str
obj_na_str<-
mf_lgrouping
nlines
pag_indices_inner
find_pag
valid_pag
have_col_fnotes
div_height
"(N=xx)"
">999.9"
">999.99"
"x.xxxx | (<0.0001)"
vert_pag_indices
label_vars<-
names(x)
insightsengineering/rlistings#8
0.3.2.2
obj
trailing_sep
pagdfrow
var_labels
insightsengineering/rtables#224
CRAN release: 2022-06-09
CRAN release: 2022-05-20
default_hsep
xx
linesep
hsep
indent_size
matrix_form
"__ (__)"
testthat
CRAN release: 2022-03-29
formats
rtables::table_shell
DM
rds (data.frame)
rds
data.frame
MatrixPrintForm( strings = NULL, spans, @@ -135,176 +77,143 @@ Usage
(character matrix) matrix of formatted, ready-to-display strings organized as they will be positioned when rendered. Elements that span more than one column must be followed by the correct number of placeholders (typically either empty strings or repeats of the value).
character matrix
(numeric matrix) matrix of same dimension as strings giving the spanning information for each element. Must be repeated to match placeholders in strings.
numeric matrix
strings
(character matrix) matrix of same dimension as strings giving the text alignment information for each element. Must be repeated to match placeholders in strings. Must be a supported text alignment. See decimal_align for allowed values.
(matrix) matrix of same dimension as strings giving the text format information for each element. Must be repeated to match placeholders in strings.
matrix
(data.frame) data frame with row-information necessary for pagination (see basic_pagdf() for more details).
basic_pagdf()
(list or NULL)NULL, or a list of paths to each leaf column, for use during horizontal pagination.
list
(integer) sequence of integers indicating how print lines correspond to semantic rows in the object. Typically this should not be set manually unless expand_newlines is set to FALSE.
integer
expand_newlines
FALSE
(list) referential footnote information, if applicable.
(numeric(1)) number of lines taken up by the values of the header (i.e. not including the divider).
numeric(1)
(numeric(1)) number of rows corresponding to the header.
(flag) does the corresponding table have "top left information" which should be treated differently when expanding newlines. Ignored if expand_newlines is FALSE.
flag
(flag) do the matrices (strings, spans, aligns) each contain a column that corresponds with row labels (rather than with table cell values). Defaults to TRUE.
spans
aligns
TRUE
(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.
(string) main title as a string.
string
(character) subtitles, as a character vector.
character
(character) page-specific titles, as a character vector.
(character). if matrix form of a listing, this contains the key columns as a character vector.
(character) main footer, as a character vector.
(character) provenance footer information, as a character vector.
(string) divider to be used between header and body sections.
(string) horizontal separator to be used for printing divisors between header and table body and between different footers.
(numeric(1)) space (in characters) between columns.
(numeric(1)) table inset. See table_inset().
table_inset()
(numeric or NULL) column rendering widths. If non-NULL, must have length equal to ncol(strings).
numeric
ncol(strings)
(numeric(1)) number of spaces to be used per level of indent (if supported by the relevant method). Defaults to 2.
(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)) number of columns to be repeated as context during horizontal pagination.
An object of class MatrixPrintForm. Currently this is implemented as an S3 class inheriting -from list with the following elements:
see argument.
as well as the following attributes:
nlines_header
nrow_header
number of columns of the table, not including any row names/row labels
The bare constructor for the MatrixPrintForm should generally only be called by matrix_form custom methods, and almost never from other code.
basic_matrix_form(iris) # calls matrix_form which calls this constructor #> $strings #> rnms Sepal.Length Sepal.Width Petal.Length Petal.Width @@ -1865,19 +1769,17 @@ ExamplesOn this page - -
# S4 method for class 'ANY' print(x, ...)
an object used to select a method.
further arguments passed to or from other methods.
basic_pagdf( rnames, labs = rnames, @@ -116,64 +58,51 @@ Usage
(character) vector of row names.
(character) vector of row labels. Defaults to rnames.
rnames
(integer) vector of row numbers. Defaults to seq_along(rnames).
seq_along(rnames)
(integer) number of lines each row requires to print. Defaults to 1 for all rows.
(character) class(es) for the rows. Defaults to "DataRow".
"DataRow"
(string) parent path that all rows should be "children of". Defaults to NULL, as usually this is not needed. It may be necessary to use "root", for some specific scenarios.
"root"
(list) list of paths to the rows. Defaults to lapply(rnames, function(x) c(parent_path, x)).
lapply(rnames, function(x) c(parent_path, x))
A data.frame suitable for use in both the MatrixPrintForm constructor and the pagination machinery.
basic_pagdf(c("hi", "there")) #> label name abs_rownumber path pos_in_siblings n_siblings self_extent #> hi hi hi 1 hi 1 2 1 @@ -188,19 +117,17 @@ ExamplesOn this page - -
ex_adsl ex_adae @@ -125,8 +67,7 @@ Usage
An object of class tbl_df (inherits from tbl, data.frame) with 1934 rows and 48 columns.
tbl_df
tbl
An object of class tbl_df (inherits from tbl, data.frame) with 1200 rows and 42 columns.
is_valid_format(x, stop_otherwise = FALSE) check_aligns(algn)
(string or function) format string or an object returned by sprintf_format()
function
sprintf_format()
(flag) whether an error should be thrown if x is not a valid format.
x
(character) a character vector that indicates the requested cell alignments.
is_valid_format returns TRUE if x is NULL, a supported format string, or a function, and +
is_valid_format
is_valid_format returns TRUE if x is NULL, a supported format string, or a function, and FALSE otherwise.
check_aligns returns TRUE if the provided alignments are supported, otherwise, an error is thrown.
check_aligns
If x is a function, no check is performed to verify that it returns a valid format.
is_valid_format("xx.x") #> [1] TRUE is_valid_format("fakeyfake") @@ -161,19 +90,17 @@ ExamplesOn this page - -
decimal_align(string_mat, align_mat)
(character matrix) "string" matrix component of MatrixPrintForm object.
(character matrix) "aligns" matrix component of MatrixPrintForm object. Should contain either dec_left, dec_right, or decimal for values to be decimal aligned.
A processed string matrix of class MatrixPrintForm with decimal-aligned values.
Left and right decimal alignment (dec_left and dec_right) differ from center decimal alignment (decimal) only when there is padding present. This may occur if column widths are set wider via parameters widths in toString or colwidths in paginate_*. More commonly, @@ -142,14 +77,12 @@
paginate_*
toString(), MatrixPrintForm()
toString()
MatrixPrintForm()
dfmf <- basic_matrix_form(mtcars[1:5, ]) aligns <- mf_aligns(dfmf) aligns[, -c(1)] <- "dec_left" @@ -172,19 +105,17 @@ ExamplesOn this page - -
default_hsep() set_default_hsep(hsep_char) @@ -122,22 +64,17 @@ Usage
(string) character that will be set in the R environment options as the default horizontal separator. Must be a single character. Use getOption("formatters_default_hsep") to get its current value (NULL if not set).
unicode 2014 (long dash for generating solid horizontal line) if in a locale that uses a UTF character set, otherwise an ASCII hyphen with a once-per-session warning.
default_hsep() #> [1] "—" set_default_hsep("o") @@ -164,19 +100,17 @@ ExamplesOn this page - -
default_page_number() set_default_page_number(page_number)
(string) single string value to set the page number format. It should be formatted similarly to the following format: "page {i}/{n}". {i} will be replaced with the current page number, and {n} will be replaced with the total page number. Current cpp is used to position the string in the bottom right corner.
"page {i}/{n}"
{i}
{n}
The page number format string (NULL if not set).
default_page_number() #> NULL set_default_page_number("page {i} of {n}") @@ -144,19 +80,17 @@ ExamplesOn this page - -
divider_height(obj) # S4 method for class 'ANY' @@ -110,46 +52,38 @@ Usage
(ANY) object.
ANY
The height, in lines of text, of the divider between header and body. Currently returns 1L for the default method.
1L
divider_height(mtcars) #> [1] 1
do_forced_paginate(obj) # S4 method for class 'ANY' @@ -116,39 +58,32 @@ Usage
(ANY) object to be paginated. The ANY method simply returns a list of length one, containing obj.
A list of sub-objects, which will be further paginated by the standard pagination algorithm.
export_as_pdf( x, file, @@ -134,167 +76,137 @@ Usage
(ANY) a table-like object to export. Must have an applicable matrix_form method.
(string) file to write to, must have .pdf extension.
.pdf
(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
(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.
Please use the pg_width argument or specify page_type instead.
Please use the pg_height argument or specify page_type instead.
(numeric(4)) the number of lines/characters of the margin on the bottom, left, top, and right sides of the page, respectively.
numeric(4)
(numeric) minimum sibling rows which must appear on either side of pagination row for a mid-subtable split to be valid. Defaults to 2 for tables. It is automatically turned off (set to 0) for listings.
(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
Please use the font_size argument instead.
(numeric(1)) line height. Defaults to 1.
(flag) whether pagination should be performed. Defaults to TRUE if page size is specified (including the default).
(string) placeholder string for page numbers. See default_page_number for more information. Defaults to NULL.
(numeric(1) or NULL) lines per page. If NA (the default), this is calculated automatically based on the specified page size). NULL indicates no vertical pagination should occur.
(numeric(1) or NULL) width (in characters) per page. If NA (the default), this is calculated automatically based on the specified page size). NULL indicates no horizontal pagination should occur.
(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()
(numeric(1)) indent size, in characters. Ignored when x is already a MatrixPrintForm object in favor of information there.
(numeric(1)) number of columns (not including row labels) to be repeated on every page. Defaults to 0.
(flag) whether the text for title, subtitles, and footnotes should be wrapped.
(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.
integer(1)
getOption("width")
"auto"
tf_wrap = FALSE
(numeric) vector of column widths (in characters) for use in vertical pagination.
(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.
logical(1)
fontspec
By default, pagination is performed with default cpp and lpp defined by specified page dimensions and margins. User-specified lpp and cpp values override this, and should be used with caution.
export_as_txt()
if (FALSE) { # \dontrun{ tf <- tempfile(fileext = ".pdf") export_as_pdf(basic_matrix_form(mtcars), file = tf, pg_height = 4) @@ -321,19 +231,17 @@ ExamplesOn this page - -
export_as_rtf( x, file = NULL, @@ -121,112 +63,90 @@ Usage
(string or NULL) if non-NULL, the path to write a text file to containing x rendered as ASCII text.
(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.
"bottom"
"left"
"top"
"right"
.5
.75
additional parameters passed to paginate_to_mpfs().
RTF export occurs via the following steps:
The table is paginated to the specified page size (vertically and horizontally).
Each separate page is converted to a MatrixPrintForm object and then to RTF-encoded text.
Separate RTF text chunks are combined and written to a single RTF file.
Conversion of MatrixPrintForm objects to RTF is done via mpf_to_rtf().
mpf_to_rtf()
export_as_txt( x, file = NULL, @@ -141,179 +83,147 @@ Usage
(character) list of names of subtables where page breaks are not allowed, regardless of other considerations. Defaults to none.
(flag) whether additional informative messages about the search for pagination breaks should be shown. Defaults to FALSE.
(string) page break symbol (defaults to "\\n\\s").
"\\n\\s"
(numeric(1)) The number of spaces to be placed between columns in the rendered table (and assumed for horizontal pagination).
If file is NULL, the full paginated and concatenated string value is returned, otherwise the output is written to file and no value (invisible NULL) is returned.
file
If x has a num_rep_cols method, the value returned by it will be used for rep_cols by default. Otherwise, 0 will be used.
num_rep_cols
If x has an applicable do_forced_paginate method, it will be invoked during the @@ -321,27 +231,24 @@
do_forced_paginate
export_as_txt(basic_matrix_form(mtcars), pg_height = 5, pg_width = 4) #> [1] " mpg cyl\noooooooooooooooooooooooooooooooo\nMazda RX4 21 6 \nMazda RX4 Wag 21 6 \nDatsun 710 22.8 4 \nHornet 4 Drive 21.4 6 \nHornet Sportabout 18.7 8 \nValiant 18.1 6 \nDuster 360 14.3 8 \nMerc 240D 24.4 4 \nMerc 230 22.8 4 \nMerc 280 19.2 6 \nMerc 280C 17.8 6 \nMerc 450SE 16.4 8 \nMerc 450SL 17.3 8 \nMerc 450SLC 15.2 8 \nCadillac Fleetwood 10.4 8 \nLincoln Continental 10.4 8 \nChrysler Imperial 14.7 8 \nFiat 128 32.4 4 \nHonda Civic 30.4 4 \nToyota Corolla 33.9 4 \nToyota Corona 21.5 4 \nDodge Challenger 15.5 8 \nAMC Javelin 15.2 8 \nCamaro Z28 13.3 8 \nPontiac Firebird 19.2 8 \nFiat X1-9 27.3 4 \nPorsche 914-2 26 4 \nLotus Europa 30.4 4 \nFord Pantera L 15.8 8 \noooooooooooooooooooooooooooooooo\n\n\n page 1 of 10\n\\s\\n disp hp \nooooooooooooooooooooooooooooooooo\nMazda RX4 160 110\nMazda RX4 Wag 160 110\nDatsun 710 108 93 \nHornet 4 Drive 258 110\nHornet Sportabout 360 175\nValiant 225 105\nDuster 360 360 245\nMerc 240D 146.7 62 \nMerc 230 140.8 95 \nMerc 280 167.6 123\nMerc 280C 167.6 123\nMerc 450SE 275.8 180\nMerc 450SL 275.8 180\nMerc 450SLC 275.8 180\nCadillac Fleetwood 472 205\nLincoln Continental 460 215\nChrysler Imperial 440 230\nFiat 128 78.7 66 \nHonda Civic 75.7 52 \nToyota Corolla 71.1 65 \nToyota Corona 120.1 97 \nDodge Challenger 318 150\nAMC Javelin 304 150\nCamaro Z28 350 245\nPontiac Firebird 400 175\nFiat X1-9 79 66 \nPorsche 914-2 120.3 91 \nLotus Europa 95.1 113\nFord Pantera L 351 264\nooooooooooooooooooooooooooooooooo\n\n\n page 2 of 10\n\\s\\n drat wt \noooooooooooooooooooooooooooooooooo\nMazda RX4 3.9 2.62 \nMazda RX4 Wag 3.9 2.875\nDatsun 710 3.85 2.32 \nHornet 4 Drive 3.08 3.215\nHornet Sportabout 3.15 3.44 \nValiant 2.76 3.46 \nDuster 360 3.21 3.57 \nMerc 240D 3.69 3.19 \nMerc 230 3.92 3.15 \nMerc 280 3.92 3.44 \nMerc 280C 3.92 3.44 \nMerc 450SE 3.07 4.07 \nMerc 450SL 3.07 3.73 \nMerc 450SLC 3.07 3.78 \nCadillac Fleetwood 2.93 5.25 \nLincoln Continental 3 5.424\nChrysler Imperial 3.23 5.345\nFiat 128 4.08 2.2 \nHonda Civic 4.93 1.615\nToyota Corolla 4.22 1.835\nToyota Corona 3.7 2.465\nDodge Challenger 2.76 3.52 \nAMC Javelin 3.15 3.435\nCamaro Z28 3.73 3.84 \nPontiac Firebird 3.08 3.845\nFiat X1-9 4.08 1.935\nPorsche 914-2 4.43 2.14 \nLotus Europa 3.77 1.513\nFord Pantera L 4.22 3.17 \noooooooooooooooooooooooooooooooooo\n\n\n page 3 of 10\n\\s\\n qsec vs am\nooooooooooooooooooooooooooooooooooooo\nMazda RX4 16.46 0 1 \nMazda RX4 Wag 17.02 0 1 \nDatsun 710 18.61 1 1 \nHornet 4 Drive 19.44 1 0 \nHornet Sportabout 17.02 0 0 \nValiant 20.22 1 0 \nDuster 360 15.84 0 0 \nMerc 240D 20 1 0 \nMerc 230 22.9 1 0 \nMerc 280 18.3 1 0 \nMerc 280C 18.9 1 0 \nMerc 450SE 17.4 0 0 \nMerc 450SL 17.6 0 0 \nMerc 450SLC 18 0 0 \nCadillac Fleetwood 17.98 0 0 \nLincoln Continental 17.82 0 0 \nChrysler Imperial 17.42 0 0 \nFiat 128 19.47 1 1 \nHonda Civic 18.52 1 1 \nToyota Corolla 19.9 1 1 \nToyota Corona 20.01 1 0 \nDodge Challenger 16.87 0 0 \nAMC Javelin 17.3 0 0 \nCamaro Z28 15.41 0 0 \nPontiac Firebird 17.05 0 0 \nFiat X1-9 18.9 1 1 \nPorsche 914-2 16.7 0 1 \nLotus Europa 16.9 1 1 \nFord Pantera L 14.5 0 1 \nooooooooooooooooooooooooooooooooooooo\n\n\n page 4 of 10\n\\s\\n gear carb\nooooooooooooooooooooooooooooooooo\nMazda RX4 4 4 \nMazda RX4 Wag 4 4 \nDatsun 710 4 1 \nHornet 4 Drive 3 1 \nHornet Sportabout 3 2 \nValiant 3 1 \nDuster 360 3 4 \nMerc 240D 4 2 \nMerc 230 4 2 \nMerc 280 4 4 \nMerc 280C 4 4 \nMerc 450SE 3 3 \nMerc 450SL 3 3 \nMerc 450SLC 3 3 \nCadillac Fleetwood 3 4 \nLincoln Continental 3 4 \nChrysler Imperial 3 4 \nFiat 128 4 1 \nHonda Civic 4 2 \nToyota Corolla 4 1 \nToyota Corona 3 1 \nDodge Challenger 3 2 \nAMC Javelin 3 2 \nCamaro Z28 3 4 \nPontiac Firebird 3 2 \nFiat X1-9 4 1 \nPorsche 914-2 5 2 \nLotus Europa 5 2 \nFord Pantera L 5 4 \nooooooooooooooooooooooooooooooooo\n\n\n page 5 of 10\n\\s\\n mpg cyl\noooooooooooooooooooooooooooooooo\nFerrari Dino 19.7 6 \nMaserati Bora 15 8 \nVolvo 142E 21.4 4 \noooooooooooooooooooooooooooooooo\n\n\n page 6 of 10\n\\s\\n disp hp \nooooooooooooooooooooooooooooooooo\nFerrari Dino 145 175\nMaserati Bora 301 335\nVolvo 142E 121 109\nooooooooooooooooooooooooooooooooo\n\n\n page 7 of 10\n\\s\\n drat wt \noooooooooooooooooooooooooooooooooo\nFerrari Dino 3.62 2.77 \nMaserati Bora 3.54 3.57 \nVolvo 142E 4.11 2.78 \noooooooooooooooooooooooooooooooooo\n\n\n page 8 of 10\n\\s\\n qsec vs am\nooooooooooooooooooooooooooooooooooooo\nFerrari Dino 15.5 0 1 \nMaserati Bora 14.6 0 1 \nVolvo 142E 18.6 1 1 \nooooooooooooooooooooooooooooooooooooo\n\n\n page 9 of 10\n\\s\\n gear carb\nooooooooooooooooooooooooooooooooo\nFerrari Dino 5 6 \nMaserati Bora 5 8 \nVolvo 142E 4 2 \nooooooooooooooooooooooooooooooooo\n\n\n page 10 of 10\n"
fmt_config(format = NULL, na_str = "NA", align = "center")
(string or function) a format label (string) or formatter function.
(string) string that should be displayed in place of missing values.
(string) alignment values should be rendered with.
An object of class fmt_config which contains the following elements:
fmt_config(format = "xx.xx", na_str = "-", align = "left") #> An object of class "fmt_config" #> Slot "format": @@ -168,19 +99,17 @@ ExamplesOn this page - -
font_lcpi( font_family = "Courier", font_size = 8, @@ -112,43 +54,34 @@ Usage
A named list with cpi and lpi, the characters and lines per inch, respectively.
cpi
lpi
This function opens a PDF graphics device, writes to a temporary file, then utilizes grid::convertWidth() and grid::convertHeight() to calculate lines per inch and characters per inch for the specified font family, size, and @@ -158,8 +91,7 @@
grid::convertWidth()
grid::convertHeight()
font_lcpi <- getFromNamespace("font_lcpi", "formatters") font_lcpi() @@ -187,19 +119,17 @@ ExamplesOn this page - -
font_spec(font_family = "Courier", font_size = 8, lineheight = 1)
(character(1)) font family to use during string width and lines-per-page calculations. You can specify "Times New Roman" as "Times" or "serif", regardless of OS. @@ -121,42 +60,35 @@
character(1)
(numeric(1)) font size to use during string width calculations and lines-per-page calculations.
(numeric(1)) line height to use during lines-per-page calculations.
Passing the output of this constructor to the rendering or pagination machinery defines a font for use when calculating word wrapping and pagination.
Specifying font in this way to, e.g., export_as_txt() or toString() will not affect the font size of the output, as these are both raw text formats. export_as_pdf() will use the specified font.
nchar_ttype(), toString(), pagination_algo, export_as_pdf()
nchar_ttype()
pagination_algo
fspec <- font_spec("Courier", 8, 1) lets <- paste(letters, collapse = "") @@ -172,19 +104,17 @@ ExamplesOn this page - -
format_value(x, format = NULL, output = c("ascii", "html"), na_str = "NA")
(ANY) the value to be formatted.
(string or function) the format label (string) or formatter function to apply to x.
(string) output type.
(character) character vector to display when the values of x are missing. If only one string is provided, it is applied for all missing values. Defaults to "NA".
Formatted text representing the cell x.
A length-zero value for na_str will be interpreted as "NA".
round_fmt()
x <- format_value(pi, format = "xx.xx") x #> [1] "3.14" @@ -168,19 +99,17 @@ ExamplesOn this page - -
Useful links:
https://insightsengineering.github.io/formatters/
https://github.com/insightsengineering/formatters/
Report bugs at https://github.com/insightsengineering/formatters/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:
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]
%||%
R/utils.R
ifnotlen0.Rd
a %||% b
(ANY) element to select only if it is not of length 0.
(ANY) element to select if a has length 0.
a
a if it is not of length 0, otherwise b.
b
6 %||% 10 #> [1] 6 @@ -145,19 +79,17 @@ ExamplesOn this page - -
formatters
formatters-package
Functions related to applying formats to values
format_value()
is_valid_format()
check_aligns()
is.wholenumber()
list_valid_format_labels()
sprintf
fmt_config()
Generics required for pagination machinery
make_row_df()
pagdfrow()
nlines()
divider_height()
main_title()
`main_title<-`()
subtitles()
`subtitles<-`()
page_titles()
`page_titles<-`()
main_footer()
`main_footer<-`()
prov_footer()
`prov_footer<-`()
all_footers()
all_titles()
num_rep_cols()
`num_rep_cols<-`()
do_forced_paginate()
Generics required for rendering table-like object to ASCII
matrix_form()
rtable
basic_matrix_form()
basic_listing_mf()
Intermediate representation for ASCII table printing
MatrixPrintForm-class
ASCII rendering-related functions which operate on MatrixPrintForm objects
spans_to_viscell()
propose_column_widths()
decimal_align()
padstr()
spread_integer()
paginate_indices()
diagnose_pagination()
pag_indices_inner()
vert_pag_indices()
Functions for assigning labels to variables in data
`var_labels<-`()
var_labels()
var_labels_remove()
var_relabel()
with_label()
obj_name()
`obj_name<-`()
obj_label()
`obj_label<-`()
obj_format()
`obj_format<-`()
obj_na_str()
`obj_na_str<-`()
obj_align()
`obj_align<-`()
Data included with the package
ex_adsl
ex_adae
ex_adaette
ex_adtte
ex_adcm
ex_adlb
ex_admh
ex_adqs
ex_adrs
ex_advs
Export into different object types
export_as_rtf()
Other documented functions used by developers of this package
print(<ANY>)
wrap_string()
wrap_txt()
split_word_ttype()
wrap_string_ttype()
`%||%`
`table_inset<-`()
mf_strings()
mf_spans()
mf_aligns()
mf_display()
mf_formats()
mf_rinfo()
mf_cinfo()
mf_has_topleft()
mf_lgrouping()
mf_rfnotes()
mf_nlheader()
mf_nrheader()
mf_colgap()
mf_fontspec()
`mf_fontspec<-`()
`mf_strings<-`()
`mf_spans<-`()
`mf_aligns<-`()
`mf_display<-`()
`mf_formats<-`()
`mf_rinfo<-`()
`mf_cinfo<-`()
`mf_lgrouping<-`()
`mf_rfnotes<-`()
`mf_nrheader<-`()
`mf_colgap<-`()
mf_ncol()
mf_nrow()
`mf_ncol<-`()
ncol(<MatrixPrintForm>)
mpf_has_rlabels()
mf_has_rlabels()
page_lcpp()
page_types()
page_dim()
ref_df_row()
default_page_number()
set_default_page_number()
Functions related to font support for pagination
open_font_dev()
close_font_dev()
debug_font_dev()
undebug_font_dev()
is.wholenumber(x, tol = .Machine$double.eps^0.5)
(numeric(1)) a numeric value.
(numeric(1)) a precision tolerance.
TRUE if x is within tol of zero, FALSE otherwise.
tol
is.wholenumber(5) #> [1] TRUE is.wholenumber(5.00000000000000001) @@ -142,19 +77,17 @@ ExamplesOn this page - -
obj_name(obj) obj_name(obj) <- value @@ -167,47 +109,38 @@ Usage
(ANY) the object.
character(1). The new label
The name, format, or label of obj for getters, or obj after modification for setters.
with_label
list_valid_format_labels() list_valid_aligns()
list_valid_format_labels() returns a nested list, with elements listing the supported 1d, 2d, +
list_valid_format_labels() returns a nested list, with elements listing the supported 1d, 2d, and 3d format strings.
list_valid_aligns() returns a character vector of valid vertical alignments.
list_valid_format_labels() #> $`1d` #> [1] "xx" "xx." "xx.x" @@ -165,19 +101,17 @@ ExamplesOn this page - -
make_row_df( tt, colwidths = NULL, @@ -146,93 +88,74 @@ Usage
(ANY) object representing the table-like object to be summarized.
(numeric) internal detail, do not set manually.
(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.
(character) path to the (sub)table represented by tt. Defaults to character().
tt
character()
(flag) internal detail, do not set manually.
(integer) internal detail, do not set manually.
(numeric(1) or NULL) maximum width for title/footer materials.
(numeric(1)) the gap to be assumed between columns, in number of spaces with font specified by fontspec.
A data.frame of row/column-structure information used by the pagination machinery.
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 @@ -244,16 +167,14 @@
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_row_df
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 @@ -261,19 +182,17 @@ ExamplesOn this page - -
matrix_form( obj, indent_rownames = FALSE, @@ -127,55 +69,43 @@ Usage
(ANY) object to be transformed into a ready-to-render form (a MatrixPrintForm object).
(flag) if TRUE, the row names column in the strings matrix of obj will have indented row names (strings pre-fixed).
(flag) whether the generated matrix form should expand rows whose values contain newlines into multiple 'physical' rows (as they will appear when rendered into ASCII). Defaults to TRUE.
A MatrixPrintForm classed list with an additional nrow_header attribute indicating the -number of pseudo "rows" the column structure defines, 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 basic_pagdf().
mf_strings(mf) mf_spans(mf) @@ -173,51 +115,40 @@ Usage
(MatrixPrintForm) a MatrixPrintForm object.
(ANY) the new value for the component in question.
MatrixPrintForm. The object.
Getters return the associated element of mf.
mf
Setters return the modified mf object.
mpf_to_rtf( mpf, colwidths = NULL, @@ -120,87 +62,70 @@ Usage
(numeric) column widths.
additional parameters passed to individual methods.
An RTF object.
This function provides a low-level coercion of a MatrixPrintForm object into text containing the corresponding table in RTF. Currently, no pagination is done at this level, and should be done prior to calling this function, though that @@ -208,19 +133,17 @@
nchar_ttype( x, fontspec = font_spec(), @@ -130,40 +72,32 @@ Usage
(character) the string(s) to calculate width(s) for.
(font_spec or NULL) if non-NULL, the font to use for the calculations (as returned by font_spec()). Defaults to "Courier", which is a monospace font. If NULL, the width will be returned in number of characters by calling nchar directly.
nchar
(numeric(1)) the tolerance to use when determining if a multiple needs to be rounded up to the next integer. See Details.
(logical(1)) whether unrounded widths should be returned. Defaults to FALSE.
String width is defined in terms of spaces within the specified font. For monospace fonts, this definition collapses to the number of characters in the string @@ -175,14 +109,12 @@
k
k+1
nchar_ttype("hi there!") #> [1] 9 @@ -192,19 +124,17 @@ ExamplesOn this page - -
nlines(x, colwidths = NULL, max_width = NULL, fontspec, col_gap = NULL) # S4 method for class 'list' @@ -116,61 +58,50 @@ Usage
(ANY) the object to be printed.
(numeric) column widths (if necessary). Principally used in rtables' method.
(numeric(1)) width that strings should be wrapped to when determining how many lines they require.
(numeric(1)) width of gap between columns in number of spaces. Only used by methods which must calculate span widths after wrapping.
The number of lines needed to render the object x.
num_rep_cols(obj) # S4 method for class 'ANY' @@ -124,41 +66,32 @@ Usage
(ANY) a table-like object.
(numeric(1)) the new number of columns to repeat.
An integer.
Absent a class-specific method, this function returns 0, indicating no always-repeated columns.
This number does not include row labels, the repetition of which is handled separately.
mpf <- basic_matrix_form(mtcars) num_rep_cols(mpf) #> [1] 0 @@ -169,19 +102,17 @@ ExamplesOn this page - -
open_font_dev(fontspec, silent = FALSE) close_font_dev() @@ -113,41 +55,31 @@ Usage
(logical(1)) If FALSE, the default, a warning will be emitted if this function switches away from an active graphics device.
open_font_dev returns a logical value indicating whether a new pdf device was opened.
open_font_dev
close_font_dev, debug_font_dev and undebug_font_dev return NULL.
close_font_dev
debug_font_dev
undebug_font_dev
In all cases the value is returned invisibly.
The font device state is an environment with four variables guaranteed to be set:
open
(logical(1)) whether a device is already open with font info
(logical(1)) whether the specified font is monospaced.
open_font_dev opens a pdf device with the specified font +
open_font_dev opens a pdf device with the specified font only if there is not one currently open with the same font. If a new device is opened, it caches spacewidth and ismonospace for use in nchar_ttype).
spacewidth
ismonospace
nchar_ttype
open_font_dev(font_spec("Times")) nchar_ttype("Hiya there", font_spec("Times")) #> [1] 17 @@ -182,19 +112,17 @@ ExamplesOn this page - -
padstr(x, n, just = list_valid_aligns(), fontspec = font_spec())
(string) a string.
(integer(1)) number of characters in the output string. If n < nchar(x), an error is thrown.
n < nchar(x)
(string) text alignment justification to use. Defaults to "center". Must be one of "center", "right", "left", "dec_right", "dec_left", or "decimal".
"center"
"dec_right"
"dec_left"
"decimal"
x, padded to be a string of length n.
n
padstr("abc", 3) #> [1] "abc" padstr("abc", 4) @@ -163,19 +96,17 @@ ExamplesOn this page - -
pag_indices_inner( pagdf, rlpp, @@ -126,156 +68,120 @@ Usage
(data.frame) a pagination info data.frame as created by either make_rows_df or make_cols_df.
make_rows_df
make_cols_df
(numeric) maximum number of row lines per page (not including header materials), including (re)printed header and context rows.
(numeric) total maximum number of row lines or content (column-wise characters) per page (including header materials and context rows). This is only for informative results with verbose = TRUE. It will print NA if not specified by the pagination machinery.
verbose = TRUE
(numeric) total number of context row lines or content (column-wise characters) per page (including header materials). Uses NA if not specified by the pagination machinery and is only for informative results with verbose = TRUE.
(flag) whether pagination is happening in row space (TRUE, the default) or column space (FALSE).
(flag) whether the table-like object being rendered has column-associated referential footnotes.
(numeric(1)) the height of the divider line when the associated object is rendered. Defaults to 1.
(numeric(1)) width of gap between columns, in same units as extent in pagdf (spaces under a particular font specification).
pagdf
(logical(1)) whether the object being paginated has row labels.
A list containing a vector of row numbers, broken up by page.
pab_indices_inner implements the core pagination algorithm (see below) for a single direction (vertical if row = TRUE (the default), horizontal otherwise) based on the pagination data frame and (already adjusted for non-body rows/columns) lines (or characters) per page.
pab_indices_inner
row = TRUE
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
mypgdf <- basic_pagdf(row.names(mtcars)) paginds <- pag_indices_inner(mypgdf, rlpp = 15, min_siblings = 0) @@ -325,19 +231,17 @@ ExamplesOn this page - -
pagdfrow( row, nm = obj_name(row), @@ -128,137 +70,111 @@ Usage
(ANY) object representing the row, which is used for default values of nm, lab, extent, and rclass if provided. Must have methods for obj_name, obj_label, and nlines, to retrieve default values of nm, lab, and extent, respectively.
nm
lab
extent
rclass
obj_name
obj_label
(string) name.
(string) label.
(numeric(1)) absolute row number.
(character or NULL) path within larger table.
(integer(1)) position among sibling rows.
(integer(1)) number of siblings (including self).
(numeric(1)) number of lines required to print the row.
(integer(1)) number of lines required to reprint all context for this row if it appears directly after pagination.
(integer) vector of row numbers to be reprinted if this row appears directly after pagination.
(integer) indent.
(string) class of row object.
(integer(1)) number of row referential footnotes for this row.
(integer(1)) number of cell referential footnotes for the cells in this row.
(integer(1)) total number of lines required by all referential footnotes.
(flag) currently ignored.
(string) the string to use as a separator below this row during printing. If NA_character_, no separator is used.
NA_character_
A single row data.frame with the appropriate columns for a pagination info data frame.
page_lcpp( page_type = page_types(), landscape = FALSE, @@ -117,74 +59,60 @@ Usage
A named list containing LPP (lines per page) and CPP (characters per page) elements suitable for use by the pagination machinery.
page_lcpp() #> $cpp #> [1] 105 @@ -225,19 +153,17 @@ ExamplesOn this page - -
page_types() page_dim(page_type)
(string) the name of a page size specification. Call page_types() for supported values.
page_types returns a character vector of supported page types
page_dim returns the dimensions (width, then height) of the selected page type.
page_dim
page_types() #> [1] "letter" "a4" "legal" page_dim("a4") @@ -141,19 +75,17 @@ ExamplesOn this page - -
paginate_indices( obj, page_type = "letter", @@ -182,166 +124,133 @@ Usage
(ANY) object to be paginated. Must have a matrix_form() method.
(page_size_spec). a pre-calculated page size specification. Typically this is not set by end users.
page_size_spec
paginate_indices returns a list with two elements of the same length: pag_row_indices and pag_col_indices.
paginate_indices
pag_row_indices
pag_col_indices
paginate_to_mpfs returns a list of MatrixPrintForm objects representing each individual page after pagination (including forced pagination if necessary).
diagnose_pagination returns a list containing:
diagnose_pagination
lpp_diagnostics
Diagnostic information regarding lines per page.
row_diagnostics
paginate_indices renders obj into a MatrixPrintForm (MPF), then uses that representation to calculate the rows and columns of obj corresponding to each page of the pagination of obj, but simply returns these indices rather than paginating obj itself (see Details for an important caveat).
For diagnose_pagination, the column labels are not displayed in the col_diagnostics element due to certain internal implementation details; rather the diagnostics are reported in terms of absolute (leaf) column position. This is a known limitation, and may eventually be changed, but the @@ -409,8 +314,7 @@
col_diagnostics
mpf <- basic_matrix_form(mtcars) paginate_indices(mpf, pg_width = 5, pg_height = 3) @@ -2689,19 +2593,17 @@ ExamplesOn this page - -
propose_column_widths(x, indent_size = 2, fontspec = font_spec())
(ANY) a MatrixPrintForm object, or an object with a matrix_form method.
A vector of column widths based on the content of x for use in printing and pagination.
mf <- basic_matrix_form(mtcars) propose_column_widths(mf) #> rnms mpg cyl disp hp drat wt qsec vs am gear carb @@ -147,19 +81,17 @@ ExamplesOn this page - -
ref_df_row( row_path = NA_character_, col_path = NA_character_, @@ -116,75 +58,61 @@ Usage
(character) row path (or NA_character_ for none).
(character) column path (or NA_character_ for none).
(integer(1)) integer position of the row.
(integer(1)) integer position of the column.
(string) symbol for the reference. NA_character_ to use the ref_index automatically.
ref_index
(integer(1)) index of the footnote, used for ordering even when symbol is not NA.
(string) the string message, not including the symbol portion ({symbol} - )
{symbol} -
A single row data frame with the appropriate columns.
round_fmt(x, digits, na_str = "NA")
(numeric(1)) value to format.
(numeric(1)) number of digits to round to, or NA to convert to a character value with no rounding.
(string) the value to return if x is NA.
A character value representing the value after rounding, containing any trailing zeros required to display exactly digits elements.
digits
This function combines the rounding behavior of R's standards-compliant round() function (see the Details section of that documentation) with the strict decimal display of sprintf(). The exact behavior is as follows:
round()
sprintf()
If x is NA, the value of na_str is returned.
If x is non-NA but digits is NA, x is converted to a character and returned.
If x and digits are both non-NA, round() is called first, and then sprintf() is used to convert the rounded value to a character with the appropriate number of trailing zeros enforced.
This differs from the base R round() function in that NA digits indicate x should be converted to character and returned unchanged whereas round(x, digits=NA) returns NA for all values of x.
round(x, digits=NA)
This behavior will differ from as.character(round(x, digits = digits)) in the case where there are @@ -164,14 +95,12 @@
as.character(round(x, digits = digits))
format_value(), round(), sprintf()
round_fmt(0, digits = 3) #> [1] "0.000" round_fmt(.395, digits = 2) @@ -186,19 +115,17 @@ ExamplesOn this page - -
spans_to_viscell(spans)
(numeric) a vector of spans, with each span value repeated for the cells it covers.
A logical vector the same length as spans indicating whether the contents of a string vector with those spans is valid.
The values of spans are assumed to be repeated such that each individual position covered by the span has the repeated value.
This means that each block of values in spans must be of a length at least equal to its value @@ -136,34 +72,30 @@
Currently no checking or enforcement is done to verify that the vector of spans is valid according to the specifications described in the Details section above.
spans_to_viscell(c(2, 2, 2, 2, 1, 3, 3, 3)) #> [1] TRUE FALSE TRUE FALSE TRUE TRUE FALSE FALSE
spread_integer(x, len)
(integer(1)) number to spread.
(integer(1)) number of times to repeat x.
If x is a scalar whole number value (see is.wholenumber()), the value x is repeated len times. Otherwise, an error is thrown.
len
spread_integer(3, 1) #> [1] 3 spread_integer(0, 3) @@ -155,19 +90,17 @@ ExamplesOn this page - -
sprintf_format(format)
(string) a format string passed to sprintf().
A formatting function which wraps and applies the specified sprintf-style format to string format.
fmtfun <- sprintf_format("(N=%i") format_value(100, format = fmtfun) #> [1] "(N=100" @@ -144,19 +79,17 @@ ExamplesOn this page - -
table_inset(obj) # S4 method for class 'MatrixPrintForm' @@ -121,49 +63,39 @@ Usage
(ANY) object to get or (recursively if necessary) set table inset for.
(string) string to use as new header/body separator.
table_inset returns the integer value that the table body (including column heading +
table_inset
table_inset returns the integer value that the table body (including column heading information and section dividers), referential footnotes, and main footer should be inset from the left alignment of the titles and provenance footers during rendering.
table_inset<- returns obj with the new table_inset value applied recursively to it and all its subtables.
table_inset<-
basic_matrix_form( df, indent_rownames = FALSE, @@ -127,56 +69,46 @@ Usage
(data.frame) a data frame.
(flag) whether row names should be indented. Being this used for testing purposes, it defaults to FALSE. If TRUE, it assigns label rows on even lines (also format is "-" and value strings are ""). Indentation works only if split labels are used (see parameters split_labels and data_labels).
"-"
""
split_labels
data_labels
(flag) whether row names should be ignored.
(flag) whether adds title and footer decorations should be added to the matrix form.
(string) indicates which column to use as split labels. If NULL, no split labels are used.
(string) indicates which column to use as data labels. It is ignored if no split_labels is present and is automatically assigned to "Analysis method" when split_labels is present, but data_labels is NULL. @@ -184,47 +116,38 @@
"Analysis method"
(numeric(1)) Number of columns to be treated as repeating columns. Defaults to 0 for basic_matrix_form and length(keycols) for basic_listing_mf. Note repeating columns are separate from row labels if present.
0
basic_matrix_form
length(keycols)
basic_listing_mf
(character) a vector of df column names that are printed first and for which repeated values are assigned "". This format is characteristic of a listing matrix form.
df
A valid MatrixPrintForm object representing df that is ready for ASCII rendering.
A valid MatrixPrintForm object representing df as a listing that is ready for ASCII rendering.
If some of the column has a obj_format assigned, it will be respected for all column values except for label rows, if present (see parameter split_labels).
basic_listing_mf(): Create a MatrixPrintForm object from data frame df that +
basic_listing_mf(): Create a MatrixPrintForm object from data frame df that respects the default formats for a listing object.
mform <- basic_matrix_form(mtcars) cat(toString(mform)) #> mpg cyl disp hp drat wt qsec vs am gear carb @@ -332,19 +255,17 @@ ExamplesOn this page - -
main_title(obj) # S4 method for class 'MatrixPrintForm' @@ -162,44 +104,36 @@ Usage
(ANY) object to extract information from.
character. New value.
A character scalar (main_title), character vector (main_footer), or vector of length zero or more (subtitles, page_titles, prov_footer) containing the relevant title/footer contents.
main_title
main_footer
subtitles
page_titles
toString(x, ...) # S4 method for class 'MatrixPrintForm' @@ -134,88 +76,72 @@ Usage
(ANY) object to be prepared for rendering.
(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
A character string containing the ASCII rendering of the table-like object represented by x.
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
mform <- basic_matrix_form(mtcars) cat(toString(mform)) #> mpg cyl disp hp drat wt qsec vs am gear carb @@ -256,19 +182,17 @@ ExamplesOn this page - -
