🙏 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/col_formatting.Rmd
col_formatting.Rmd
vignettes/pagination.Rmd
pagination.Rmd
vignettes/ref_footnotes.Rmd
ref_footnotes.Rmd
Gabriel Becker. Author. original creator of the package
F. Hoffmann-La Roche AG. Copyright holder, funder.
Becker G, Waddell A, Zhu J, Garolini D, de la Rua E (2025). rlistings: Clinical Trial Style Data Readout Listings. -R package version 0.2.10.9000, +R package version 0.2.10.9001, https://github.com/insightsengineering/rlistings/, https://insightsengineering.github.io/rlistings/.
@Manual{, title = {rlistings: Clinical Trial Style Data Readout Listings}, author = {Gabriel Becker and Adrian Waddell and Joe Zhu and Davide Garolini and Emily {de la Rua}}, year = {2025}, - note = {R package version 0.2.10.9000, + note = {R package version 0.2.10.9001, https://github.com/insightsengineering/rlistings/}, url = {https://insightsengineering.github.io/rlistings/}, }
CRAN release: 2025-01-09
difftime
CRAN release: 2024-06-20
truetype
formatters
paginate_listing
col_gap
CRAN release: 2024-04-15
split_into_pages_by_var
pag_listing_indices
paginate_to_mpfs
CRAN release: 2023-12-06
styler
add_listing_col
export_as_txt
as_listing
matrix_form
NA
CRAN release: 2023-08-26
num_rep_cols
default_formatting
col_formatting
unique_rows
left
testthat
CRAN release: 2023-05-25
CRAN release: 2023-03-17
page_type
pg_width
pg_height
font_family
font_size
lpp
cpp
cols
disp_cols
rlistings-package
markdown
matrix_form(lsting, TRUE)
dplyr
magrittr
var_labels
print(<listing_df>)
toString(<listing_df>)
`[`(<listing_df>)
main_title(<listing_df>)
subtitles(<listing_df>)
main_footer(<listing_df>)
prov_footer(<listing_df>)
`main_title<-`(<listing_df>)
`subtitles<-`(<listing_df>)
`main_footer<-`(<listing_df>)
`prov_footer<-`(<listing_df>)
num_rep_cols(<listing_df>)
listing_df
as_listing()
as_keycol()
is_keycol()
get_keycols()
listing_dispcols()
add_listing_dispcol()
`listing_dispcols<-`()
add_listing_col()
data.frame
tibble
make_row_df(<listing_df>)
matrix_form(<listing_df>)
rtable
paginate_listing()
split_into_pages_by_var()
# S3 method for class 'listing_df' print( x, @@ -152,95 +97,76 @@ Usage
(listing_df) the listing.
(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.
numeric
NULL
x
ncol(x) + 1
(flag) whether the text for title, subtitles, and footnotes should be wrapped.
flag
(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)
string
getOption("width")
"auto"
tf_wrap = FALSE
(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)) space (in characters) between columns.
numeric(1)
additional parameters passed to formatters::toString().
formatters::toString()
(any) object passed to base [ methods.
any
[
relevant for matrices and arrays. If TRUE the result is coerced to the lowest possible dimension (see the examples). This only works for extracting elements, not for the replacement. See drop for further details.
TRUE
drop
typically an array-like R object of a similar class as x.
Accessor methods return the value of the aspect of obj.
obj
Setter methods return obj with the relevant element of the listing updated.
lsting <- as_listing(mtcars) main_title(lsting) <- "Hi there" @@ -250,19 +176,17 @@ ExamplesOn this page - -
R/rlistings.R
listings.Rd
as_listing( df, key_cols = names(df)[1], @@ -151,43 +95,35 @@ Usage
(data.frame or listing_df) the data.frame to be converted to a listing or listing_df to be modified.
(character) vector of names of columns which should be treated as key columns when rendering the listing. Key columns allow you to group repeat occurrences.
character
(character or NULL) vector of names of non-key columns which should be displayed when the listing is rendered. Defaults to all columns of df not named in key_cols or non_disp_cols.
df
key_cols
non_disp_cols
(character or NULL) vector of names of non-key columns to be excluded as display columns. All other non-key columns are treated as display columns. Ignored if disp_cols is non-NULL.
(flag) whether only unique rows should be included in the listing. Defaults to FALSE.
FALSE
(list) a named list of default column format configurations to apply when rendering the listing. Each name-value pair consists of a name corresponding to a data class (or "numeric" for all unspecified numeric classes) and a value of type fmt_config with the format configuration that should be @@ -196,97 +132,80 @@
list
fmt_config
(list) a named list of custom column formatting configurations to apply to specific columns when rendering the listing. Each name-value pair consists of a name corresponding to a column name and a value of type fmt_config with the formatting configuration that should be implemented for that column. Objects of type fmt_config can take 3 arguments: format, na_str, and align. Defaults to NULL.
format
na_str
align
(string or NULL) the main title for the listing, or NULL (the default).
(character or NULL) a vector of subtitles for the listing, or NULL (the default).
(character or NULL) a vector of main footer lines for the listing, or NULL (the default).
(character or NULL) a vector of provenance footer lines for the listing, or NULL (the default). Each string element is placed on a new line.
(character or NULL) the name of a variable for on the listing should be split into pages, with each page corresponding to one unique value/level of the variable. See split_into_pages_by_var() for more details.
(string) name of a column vector from a listing_df object to be annotated as a key column.
(character) vector of names of columns to be added to the set of display columns.
(string) new value.
(string) name of the existing or new column to be displayed when the listing is rendered.
(function or NULL) a function which accepts df and returns the vector for a new column, which is added to df as name, or NULL if marking an existing column as a listing column.
function
name
(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.
A listing_df object, sorted by its key columns.
df with name created (if necessary) and marked for display during rendering.
At its core, a listing_df object is a tbl_df object with a customized print method and support for the formatting and pagination machinery provided by the formatters package.
tbl_df
dat <- ex_adae # This example demonstrates the listing with key_cols (values are grouped by USUBJID) and @@ -464,19 +382,17 @@ ExamplesOn this page - -
# S4 method for class 'listing_df' make_row_df( tt, @@ -124,107 +69,87 @@ Usage
(listing_df) the listing to be rendered.
(numeric) internal detail, do not set manually.
(flag) ignored, as listings do not have non-visible structural elements.
(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.
integer
a data.frame with pagination information.
formatters::make_row_df()
lsting <- as_listing(mtcars) mf <- matrix_form(lsting)
# S4 method for class 'listing_df' matrix_form( obj, @@ -120,74 +65,61 @@ Usage
(ANY) object to be transformed into a ready-to-render form (a MatrixPrintForm object).
ANY
MatrixPrintForm
(flag) silently ignored, as listings do not have row names nor indenting structure.
(flag) this should always be TRUE for listings. We keep it for debugging reasons.
(numeric(1)) the gap to be assumed between columns, in number of spaces with font specified by fontspec.
fontspec
a formatters::MatrixPrintForm object.
formatters::matrix_form()
paginate_listing( lsting, page_type = "letter", @@ -139,132 +84,108 @@ Usage
(listing_df or list) the listing or list of listings to paginate.
(string) name of a page type. See page_types. Ignored when pg_width and pg_height are set directly.
page_types
(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.
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.
(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) number of rows/lines (excluding titles and footers) to include per page. Standard is 70 while NULL disables vertical pagination.
70
(numeric(1) or NULL) width (in characters) of the pages for horizontal pagination. NULL (the default) indicates no horizontal pagination should be done.
(numeric) vector of column widths (in characters) for use in vertical pagination.
(numeric(1)) number of columns (not including row labels) to be repeated on every page. Defaults to 0.
(numeric(1)) width of gap between columns, in same units as extent in pagdf (spaces under a particular font specification).
pagdf
(flag) whether additional informative messages about the search for pagination breaks should be shown. Defaults to FALSE.
(flag) whether the paginated listing should be printed to the console (cat(toString(x))).
cat(toString(x))
A list of listing_df objects where each list element corresponds to a separate page.
dat <- ex_adae lsting <- as_listing(dat[1:25, ], disp_cols = c("USUBJID", "AESOC", "RACE", "AETOXGR", "BMRKR1")) mat <- matrix_form(lsting) @@ -561,19 +482,17 @@ ExamplesOn this page - -
These objects are imported from other packages. Follow the links below to see their documentation.
dat <- ex_adae lsting <- as_listing(dat[1:25, ], key_cols = c("USUBJID", "AESOC")) %>% @@ -1264,19 +1207,17 @@ Examples
Useful links:
https://insightsengineering.github.io/rlistings/
https://github.com/insightsengineering/rlistings/
Report bugs at https://github.com/insightsengineering/rlistings/issues
Maintainer: Joe Zhu joe.zhu@roche.com (ORCID)
Authors:
Gabriel Becker gabembecker@gmail.com (original creator of the package)
Adrian Waddell adrian.waddell@gene.com
Davide Garolini davide.garolini@roche.com
Emily de la Rua emily.de_la_rua@contractors.roche.com
Other contributors:
Abinaya Yogasekaram abinaya.yogasekaram@contractors.roche.com [contributor]
F. Hoffmann-La Roche AG [copyright holder, funder]
split_into_pages_by_var(lsting, var, page_prefix = var)
(listing_df) the listing to split.
(string) name of the variable to split on. If the column is a factor, the resulting list follows the order of the levels.
(string) prefix to be appended with the split value (var level), at the end of the subtitles, corresponding to each resulting list element (listing).
var
A list of lsting_df objects each corresponding to a unique value of var.
lsting_df
This function should only be used after the complete listing has been created. The listing cannot be modified further after applying this function.
dat <- ex_adae[1:20, ] lsting <- as_listing( @@ -216,19 +152,17 @@ ExamplesOn this page - -
format_colvector(df, colnm, colvec = df[[colnm]]) vec_nlines(vec, max_width = NULL, fontspec = dflt_courier) @@ -118,58 +63,47 @@ Usage
(string) column name.
(vector) column values based on colnm.
vector
colnm
(vector) a vector.
(numeric(1) or NULL) the width to render the column with.
(numeric) a vector of the number of lines element-wise that will be needed to render the elements of vec to width max_width.
vec
max_width
