Title: | Graphs and Tables for OMOP Results |
---|---|
Description: | Provides methods to transform omop_result objects into formatted tables and figures, facilitating the visualisation of study results working with the Observational Medical Outcomes Partnership (OMOP) Common Data Model. |
Authors: | Martí Català [aut] |
Maintainer: | Núria Mercadé-Besora <[email protected]> |
License: | Apache License (>= 2) |
Version: | 1.0.0 |
Built: | 2025-02-15 06:58:53 UTC |
Source: | CRAN |
<summarised_result>
objectCreate a bar plot visualisation from a <summarised_result>
object
barPlot( result, x, y, width = NULL, just = 0.5, facet = NULL, colour = NULL, label = character() )
barPlot( result, x, y, width = NULL, just = 0.5, facet = NULL, colour = NULL, label = character() )
result |
A |
x |
Column or estimate name that is used as x variable. |
y |
Column or estimate name that is used as y variable. |
width |
Bar width, as in |
just |
Adjustment for column placement, as in |
facet |
Variables to facet by, a formula can be provided to specify which variables should be used as rows and which ones as columns. |
colour |
Columns to use to determine the colors. |
label |
Character vector with the columns to display interactively in
|
A plot object.
result <- mockSummarisedResult() |> dplyr::filter(variable_name == "age") barPlot( result = result, x = "cohort_name", y = "mean", facet = c("age_group", "sex"), colour = "sex")
result <- mockSummarisedResult() |> dplyr::filter(variable_name == "age") barPlot( result = result, x = "cohort_name", y = "mean", facet = c("age_group", "sex"), colour = "sex")
<summarised_result>
objectCreate a box plot visualisation from a <summarised_result>
object
boxPlot( result, x, lower = "q25", middle = "median", upper = "q75", ymin = "min", ymax = "max", facet = NULL, colour = NULL, label = character() )
boxPlot( result, x, lower = "q25", middle = "median", upper = "q75", ymin = "min", ymax = "max", facet = NULL, colour = NULL, label = character() )
result |
A |
x |
Columns to use as x axes. |
lower |
Estimate name for the lower quantile of the box. |
middle |
Estimate name for the middle line of the box. |
upper |
Estimate name for the upper quantile of the box. |
ymin |
Estimate name for the lower limit of the bars. |
ymax |
Estimate name for the upper limit of the bars. |
facet |
Variables to facet by, a formula can be provided to specify which variables should be used as rows and which ones as columns. |
colour |
Columns to use to determine the colors. |
label |
Character vector with the columns to display interactively in
|
A ggplot2 object.
dplyr::tibble(year = "2000", q25 = 25, median = 50, q75 = 75, min = 0, max = 100) |> boxPlot(x = "year")
dplyr::tibble(year = "2000", q25 = 25, median = 50, q75 = 75, min = 0, max = 100) |> boxPlot(x = "year")
This function styles character vectors or column names in a data frame. The styling function can be customised, or you can provide specific replacements for certain values.
customiseText( x, fun = function(x) stringr::str_to_sentence(gsub("_", " ", x)), custom = NULL, keep = NULL )
customiseText( x, fun = function(x) stringr::str_to_sentence(gsub("_", " ", x)), custom = NULL, keep = NULL )
x |
A character vector to style text. |
fun |
A styling function to apply to text in |
custom |
A named character vector indicating custom names for specific
values in |
keep |
Either a character vector of names to keep unchanged. If NULL, all names will be styled. |
A character vector of styled text or a data frame with styled column names.
# Styling a character vector customiseText(c("some_column_name", "another_column")) # Custom styling for specific values customiseText(x = c("some_column", "another_column"), custom = c("Custom Name" = "another_column")) # Keeping specific values unchanged customiseText(x = c("some_column", "another_column"), keep = "another_column") # Styling column names and variables in a data frame dplyr::tibble( some_column = c("hi_there", "rename_me", "example", "to_keep"), another_column = 1:4, to_keep = "as_is" ) |> dplyr::mutate( "some_column" = customiseText(some_column, custom = c("EXAMPLE" = "example"), keep = "to_keep") ) |> dplyr::rename_with(.fn = ~ customiseText(.x, keep = "to_keep"))
# Styling a character vector customiseText(c("some_column_name", "another_column")) # Custom styling for specific values customiseText(x = c("some_column", "another_column"), custom = c("Custom Name" = "another_column")) # Keeping specific values unchanged customiseText(x = c("some_column", "another_column"), keep = "another_column") # Styling column names and variables in a data frame dplyr::tibble( some_column = c("hi_there", "rename_me", "example", "to_keep"), another_column = 1:4, to_keep = "as_is" ) |> dplyr::mutate( "some_column" = customiseText(some_column, custom = c("EXAMPLE" = "example"), keep = "to_keep") ) |> dplyr::rename_with(.fn = ~ customiseText(.x, keep = "to_keep"))
Returns an empty plot
emptyPlot()
emptyPlot()
An empty ggplot object
emptyPlot()
emptyPlot()
Returns an empty table
emptyTable(type = "gt")
emptyTable(type = "gt")
type |
The desired format of the output table. See |
An empty table of the class specified in type
emptyTable(type = "flextable")
emptyTable(type = "flextable")
Formats estimate_name and estimate_value columns by changing the name of the estimate name and/or joining different estimates together in a single row.
formatEstimateName( result, estimateName = NULL, keepNotFormatted = TRUE, useFormatOrder = TRUE )
formatEstimateName( result, estimateName = NULL, keepNotFormatted = TRUE, useFormatOrder = TRUE )
result |
A |
estimateName |
Named list of estimate name's to join, sorted by computation order. Indicate estimate_name's between <...>. |
keepNotFormatted |
Whether to keep rows not formatted. |
useFormatOrder |
Whether to use the order in which estimate names appear in the estimateName (TRUE), or use the order in the input dataframe (FALSE). |
A <summarised_result>
object.
result <- mockSummarisedResult() result |> formatEstimateName( estimateName = c( "N (%)" = "<count> (<percentage>%)", "N" = "<count>" ), keepNotFormatted = FALSE )
result <- mockSummarisedResult() result |> formatEstimateName( estimateName = c( "N (%)" = "<count> (<percentage>%)", "N" = "<count>" ), keepNotFormatted = FALSE )
Formats the estimate_value column of <summarised_result>
object by editing
number of decimals, decimal and thousand/millions separator marks.
formatEstimateValue( result, decimals = c(integer = 0, numeric = 2, percentage = 1, proportion = 3), decimalMark = ".", bigMark = "," )
formatEstimateValue( result, decimals = c(integer = 0, numeric = 2, percentage = 1, proportion = 3), decimalMark = ".", bigMark = "," )
result |
A |
decimals |
Number of decimals per estimate type (integer, numeric, percentage, proportion), estimate name, or all estimate values (introduce the number of decimals). |
decimalMark |
Decimal separator mark. |
bigMark |
Thousand and millions separator mark. |
A <summarised_result>
.
result <- mockSummarisedResult() result |> formatEstimateValue(decimals = 1) result |> formatEstimateValue(decimals = c(integer = 0, numeric = 1)) result |> formatEstimateValue(decimals = c(numeric = 1, count = 0))
result <- mockSummarisedResult() result |> formatEstimateValue(decimals = 1) result |> formatEstimateValue(decimals = c(integer = 0, numeric = 1)) result |> formatEstimateValue(decimals = c(numeric = 1, count = 0))
Pivots a <summarised_result>
object based on the column names in header,
generating specific column names for subsequent header formatting in
formatTable function.
formatHeader( result, header, delim = "\n", includeHeaderName = TRUE, includeHeaderKey = TRUE )
formatHeader( result, header, delim = "\n", includeHeaderName = TRUE, includeHeaderKey = TRUE )
result |
A |
header |
Names of the variables to make headers. |
delim |
Delimiter to use to separate headers. |
includeHeaderName |
Whether to include the column name as header. |
includeHeaderKey |
Whether to include the header key (header, header_name, header_level) before each header type in the column names. |
A tibble with rows pivotted into columns with key names for subsequent header formatting.
result <- mockSummarisedResult() result |> formatHeader( header = c( "Study cohorts", "group_level", "Study strata", "strata_name", "strata_level" ), includeHeaderName = FALSE )
result <- mockSummarisedResult() result |> formatHeader( header = c( "Study cohorts", "group_level", "Study strata", "strata_name", "strata_level" ), includeHeaderName = FALSE )
Creates a flextable object from a dataframe using a delimiter to span the header, and allows to easily customise table style.
formatTable( x, type = "gt", delim = "\n", style = "default", na = "-", title = NULL, subtitle = NULL, caption = NULL, groupColumn = NULL, groupAsColumn = FALSE, groupOrder = NULL, merge = NULL )
formatTable( x, type = "gt", delim = "\n", style = "default", na = "-", title = NULL, subtitle = NULL, caption = NULL, groupColumn = NULL, groupAsColumn = FALSE, groupOrder = NULL, merge = NULL )
x |
A dataframe. |
type |
The desired format of the output table. See |
delim |
Delimiter. |
style |
Named list that specifies how to style the different parts of
the gt or flextable table generated. Accepted style entries are: title,
subtitle, header, header_name, header_level, column_name, group_label, and
body.
Alternatively, use "default" to get visOmopResults style, or NULL for
gt/flextable style.
Keep in mind that styling code is different for gt and flextable. To see
the "deafult" style code use |
na |
How to display missing values. Not used for "datatable". |
title |
Title of the table, or NULL for no title. Not used for "datatable". |
subtitle |
Subtitle of the table, or NULL for no subtitle. Not used for "datatable". |
caption |
Caption for the table, or NULL for no caption. Text in
markdown formatting style (e.g. |
groupColumn |
Specifies the columns to use for group labels.
By default, the new group name will be a combination of the column names,
joined by "_". To assign a custom group name, provide a named list such as:
list( |
groupAsColumn |
Whether to display the group labels as a column (TRUE) or rows (FALSE). Not used for "datatable". |
groupOrder |
Order in which to display group labels. Not used for "datatable". |
merge |
Names of the columns to merge vertically when consecutive row cells have identical values. Alternatively, use "all_columns" to apply this merging to all columns, or use NULL to indicate no merging. Not used for "datatable". |
A flextable object.
A flextable or gt object.
# Example 1 mockSummarisedResult() |> formatEstimateValue(decimals = c(integer = 0, numeric = 1)) |> formatHeader( header = c("Study strata", "strata_name", "strata_level"), includeHeaderName = FALSE ) |> formatTable( type = "flextable", style = "default", na = "--", title = "fxTable example", subtitle = NULL, caption = NULL, groupColumn = "group_level", groupAsColumn = TRUE, groupOrder = c("cohort1", "cohort2"), merge = "all_columns" ) # Example 2 mockSummarisedResult() |> formatEstimateValue(decimals = c(integer = 0, numeric = 1)) |> formatHeader(header = c("Study strata", "strata_name", "strata_level"), includeHeaderName = FALSE) |> formatTable( type = "gt", style = list("header" = list( gt::cell_fill(color = "#d9d9d9"), gt::cell_text(weight = "bold")), "header_level" = list(gt::cell_fill(color = "#e1e1e1"), gt::cell_text(weight = "bold")), "column_name" = list(gt::cell_text(weight = "bold")), "title" = list(gt::cell_text(weight = "bold"), gt::cell_fill(color = "#c8c8c8")), "group_label" = gt::cell_fill(color = "#e1e1e1")), na = "--", title = "gtTable example", subtitle = NULL, caption = NULL, groupColumn = "group_level", groupAsColumn = FALSE, groupOrder = c("cohort1", "cohort2"), merge = "all_columns" )
# Example 1 mockSummarisedResult() |> formatEstimateValue(decimals = c(integer = 0, numeric = 1)) |> formatHeader( header = c("Study strata", "strata_name", "strata_level"), includeHeaderName = FALSE ) |> formatTable( type = "flextable", style = "default", na = "--", title = "fxTable example", subtitle = NULL, caption = NULL, groupColumn = "group_level", groupAsColumn = TRUE, groupOrder = c("cohort1", "cohort2"), merge = "all_columns" ) # Example 2 mockSummarisedResult() |> formatEstimateValue(decimals = c(integer = 0, numeric = 1)) |> formatHeader(header = c("Study strata", "strata_name", "strata_level"), includeHeaderName = FALSE) |> formatTable( type = "gt", style = list("header" = list( gt::cell_fill(color = "#d9d9d9"), gt::cell_text(weight = "bold")), "header_level" = list(gt::cell_fill(color = "#e1e1e1"), gt::cell_text(weight = "bold")), "column_name" = list(gt::cell_text(weight = "bold")), "title" = list(gt::cell_text(weight = "bold"), gt::cell_fill(color = "#c8c8c8")), "group_label" = gt::cell_fill(color = "#e1e1e1")), na = "--", title = "gtTable example", subtitle = NULL, caption = NULL, groupColumn = "group_level", groupAsColumn = FALSE, groupOrder = c("cohort1", "cohort2"), merge = "all_columns" )
<summarised_result>
object filled with mock dataCreates an object of the class <summarised_result>
with mock data
for illustration purposes.
mockSummarisedResult()
mockSummarisedResult()
An object of the class <summarised_result>
with mock data.
mockSummarisedResult()
mockSummarisedResult()
Names of the columns that can be used in the input arguments for the plot functions.
plotColumns(result)
plotColumns(result)
result |
A |
A character vector of supported columns for plots.
result <- mockSummarisedResult() plotColumns(result)
result <- mockSummarisedResult() plotColumns(result)
<summarised_result>
objectCreate a scatter plot visualisation from a <summarised_result>
object
scatterPlot( result, x, y, line, point, ribbon, ymin = NULL, ymax = NULL, facet = NULL, colour = NULL, group = colour, label = character() )
scatterPlot( result, x, y, line, point, ribbon, ymin = NULL, ymax = NULL, facet = NULL, colour = NULL, group = colour, label = character() )
result |
A |
x |
Column or estimate name that is used as x variable. |
y |
Column or estimate name that is used as y variable |
line |
Whether to plot a line using |
point |
Whether to plot points using |
ribbon |
Whether to plot a ribbon using |
ymin |
Lower limit of error bars, if provided is plot using
|
ymax |
Upper limit of error bars, if provided is plot using
|
facet |
Variables to facet by, a formula can be provided to specify which variables should be used as rows and which ones as columns. |
colour |
Columns to use to determine the colors. |
group |
Columns to use to determine the group. |
label |
Character vector with the columns to display interactively in
|
A plot object.
result <- mockSummarisedResult() |> dplyr::filter(variable_name == "age") scatterPlot( result = result, x = "cohort_name", y = "mean", line = TRUE, point = TRUE, ribbon = FALSE, facet = age_group ~ sex)
result <- mockSummarisedResult() |> dplyr::filter(variable_name == "age") scatterPlot( result = result, x = "cohort_name", y = "mean", line = TRUE, point = TRUE, ribbon = FALSE, facet = age_group ~ sex)
Names of the columns that can be used in the input arguments for the table functions.
tableColumns(result)
tableColumns(result)
result |
A |
A character vector of supported columns for tables.
result <- mockSummarisedResult() tableColumns(result)
result <- mockSummarisedResult() tableColumns(result)
visOmopTable()
and visTable()
This function provides a list of allowed inputs for the .option
argument in
visOmopTable()
and visTable()
, and their corresponding default values.
tableOptions()
tableOptions()
A named list of default options for table customisation.
tableOptions()
tableOptions()
Supported predefined styles for formatted tables
tableStyle(type = "gt")
tableStyle(type = "gt")
type |
Character string specifying the formatted table class.
See |
A code expression for the selected style and table type.
tableStyle("gt") tableStyle("flextable")
tableStyle("gt") tableStyle("flextable")
This function returns the supported table classes that can be used in the
type
argument of visOmopTable()
, visTable()
, and formatTable()
functions.
tableType()
tableType()
A character vector of supported table types.
tableType()
tableType()
Apply visOmopResults default styling to a ggplot
themeVisOmop(fontsizeRef = 10)
themeVisOmop(fontsizeRef = 10)
fontsizeRef |
An integer to use as reference when adjusting label fontsize. |
result <- mockSummarisedResult() |> dplyr::filter(variable_name == "age") barPlot( result = result, x = "cohort_name", y = "mean", facet = c("age_group", "sex"), colour = "sex") + themeVisOmop()
result <- mockSummarisedResult() |> dplyr::filter(variable_name == "age") barPlot( result = result, x = "cohort_name", y = "mean", facet = c("age_group", "sex"), colour = "sex") + themeVisOmop()
<summarised_result>
object into a gt, flextable, or tibble objectThis function combines the functionalities of formatEstimateValue()
,
estimateName()
, formatHeader()
, and formatTable()
into a single function specifically for <summarised_result>
objects.
visOmopTable( result, estimateName = character(), header = character(), settingsColumn = character(), groupColumn = character(), rename = character(), type = "gt", hide = character(), columnOrder = character(), factor = list(), showMinCellCount = TRUE, .options = list() )
visOmopTable( result, estimateName = character(), header = character(), settingsColumn = character(), groupColumn = character(), rename = character(), type = "gt", hide = character(), columnOrder = character(), factor = list(), showMinCellCount = TRUE, .options = list() )
result |
A |
estimateName |
A named list of estimate names to join, sorted by
computation order. Use |
header |
A vector specifying the elements to include in the header. The order of elements matters, with the first being the topmost header. Elements in header can be:
|
settingsColumn |
A character vector with the names of settings to
include in the table. To see options use |
groupColumn |
Columns to use as group labels, to see options use
*tidy: The tidy format applied to column names replaces "_" with a space and
converts to sentence case. Use |
rename |
A named vector to customise column names, e.g., c("Database name" = "cdm_name"). The function renames all column names not specified here into a tidy* format. |
type |
The desired format of the output table. See |
hide |
Columns to drop from the output table. By default, |
columnOrder |
Character vector establishing the position of the columns in the formatted table. Columns in either header, groupColumn, or hide will be ignored. |
factor |
A named list where names refer to columns (see available columns
in |
showMinCellCount |
If |
.options |
A named list with additional formatting options.
|
A tibble, gt, or flextable object.
result <- mockSummarisedResult() result |> visOmopTable( estimateName = c("N%" = "<count> (<percentage>)", "N" = "<count>", "Mean (SD)" = "<mean> (<sd>)"), header = c("group"), rename = c("Database name" = "cdm_name"), groupColumn = strataColumns(result) )
result <- mockSummarisedResult() result |> visOmopTable( estimateName = c("N%" = "<count> (<percentage>)", "N" = "<count>", "Mean (SD)" = "<mean> (<sd>)"), header = c("group"), rename = c("Database name" = "cdm_name"), groupColumn = strataColumns(result) )
<data.table>
This function combines the functionalities of formatEstimateValue()
,
formatEstimateName()
, formatHeader()
, and formatTable()
into a single function. While it does not require the input table to be
a <summarised_result>
, it does expect specific fields to apply some
formatting functionalities.
visTable( result, estimateName = character(), header = character(), groupColumn = character(), rename = character(), type = "gt", hide = character(), .options = list() )
visTable( result, estimateName = character(), header = character(), groupColumn = character(), rename = character(), type = "gt", hide = character(), .options = list() )
result |
A table to format. |
estimateName |
A named list of estimate names to join, sorted by
computation order. Use |
header |
A vector specifying the elements to include in the header.
The order of elements matters, with the first being the topmost header.
The vector elements can be column names or labels for overall headers.
The table must contain an |
groupColumn |
Columns to use as group labels. By default, the name of the new group will be the tidy* column names separated by ";". To specify a custom group name, use a named list such as: list("newGroupName" = c("variable_name", "variable_level")). *tidy: The tidy format applied to column names replaces "_" with a space and
converts them to sentence case. Use |
rename |
A named vector to customise column names, e.g., c("Database name" = "cdm_name"). The function will rename all column names not specified here into a tidy* format. |
type |
The desired format of the output table. See |
hide |
Columns to drop from the output table. |
.options |
A named list with additional formatting options.
|
A tibble, gt, or flextable object.
result <- mockSummarisedResult() result |> visTable( estimateName = c("N%" = "<count> (<percentage>)", "N" = "<count>", "Mean (SD)" = "<mean> (<sd>)"), header = c("Estimate"), rename = c("Database name" = "cdm_name"), groupColumn = c("strata_name", "strata_level"), hide = c("additional_name", "additional_level", "estimate_type", "result_type") )
result <- mockSummarisedResult() result |> visTable( estimateName = c("N%" = "<count> (<percentage>)", "N" = "<count>", "Mean (SD)" = "<mean> (<sd>)"), header = c("Estimate"), rename = c("Database name" = "cdm_name"), groupColumn = c("strata_name", "strata_level"), hide = c("additional_name", "additional_level", "estimate_type", "result_type") )