Package {uteals}

Decorators and transformators for teal modules.

Description

Provides decorator and transformator modules for teal modules.

Author(s)

Maintainer: Peyman Eshghi peymaan.es@gmail.com

Authors:

• Peyman Eshghi peymaan.es@gmail.com

• Nadia Abraham NAbraha5@ITS.JNJ.com

• Chanchal Bhalla CBhalla@ITS.JNJ.com

• Pranith Gourisetty PGourise@ITS.JNJ.com

• Sohan Lal SLal8@ITS.JNJ.com

• Przemyslaw Posiadala PPosiada@ITS.JNJ.com

• Alina Tselinina ATselini@ITS.JNJ.com

• Konrad Pagacz konrad.pagacz@gmail.com

Other contributors:

• PHUSE [copyright holder]

See Also

Useful links:

• https://github.com/phuse-org/uteals

Class BlockConditions

Description

This class represents a collection of conditions used for filtering datasets.

Slots

conditions

A list of conditions, where each condition is a list containing variable, operator, and value.

ReportManager Object

Description

This can be used to manage state of report, load and save them into file It will create shiny::reactiveVal variables and load report list from report_path

Public fields

Methods

Public methods

• ReportManager$new()

• ReportManager$list_reports()

• ReportManager$set_current_report_title()

• ReportManager$get_abs_report_path()

• ReportManager$save_report_files()

• ReportManager$load_report()

• ReportManager$merge_reports()

• ReportManager$reset()

• ReportManager$delete_report()

• ReportManager$is_locked_by_other()

• ReportManager$rename_report()

• ReportManager$is_new_report()

• ReportManager$create_new_report()

• ReportManager$auto_save_observer()

• ReportManager$unlock_report_public()

• ReportManager$release_lock()

• ReportManager$setup_csv_download()

• ReportManager$export_tables_to_csv()

• ReportManager$rebuild_report()

• ReportManager$clone()

ReportManager$new()

This can be used to manage state of report, load and save them into file It will create shiny::reactiveVal variables and load report list from reports_path

Usage

ReportManager$new(reports_path, session)

Arguments

Returns

ReportManager object List available reports from objects' reports_path

ReportManager$list_reports()

Usage

ReportManager$list_reports()

Returns

data.frame with fields reports, created_by, locked_by, and last_rebuild Method for storing loaded report title inside object. This assigns a value in current_report_title field

ReportManager$set_current_report_title()

Usage

ReportManager$set_current_report_title(title_or_index)

Arguments

ReportManager$get_abs_report_path()

Usage

ReportManager$get_abs_report_path(title)

Arguments

Returns

(character) A path of desired report Save report with provided title This utilizes methods from teal.reporter::Reporter to store files required to load and save reports If a report with specific title exists, it will overwrite it.

ReportManager$save_report_files()

Usage

ReportManager$save_report_files(report_title, reporter, first = FALSE)

Arguments

ReportManager$load_report()

Usage

ReportManager$load_report(selected_title, reporter, skip_lock = FALSE)

Arguments

ReportManager$merge_reports()

Usage

ReportManager$merge_reports(x_title, y_title, reporter)

Arguments

ReportManager$reset()

Usage

ReportManager$reset()

Returns

the return of self$list_reports() Delete report

ReportManager$delete_report()

Usage

ReportManager$delete_report(selected_title)

Arguments

ReportManager$is_locked_by_other()

Usage

ReportManager$is_locked_by_other(
  report_title,
  verbose = TRUE,
  message_type = "error"
)

Arguments

Returns

logical(1) TRUE if locked by another user, FALSE if unlocked or locked by me Rename report

ReportManager$rename_report()

Usage

ReportManager$rename_report(old_title, new_title, reporter)

Arguments

ReportManager$is_new_report()

Usage

ReportManager$is_new_report(reporter)

Arguments

Returns

logical indicating if this is a new report Create new report with title

ReportManager$create_new_report()

Usage

ReportManager$create_new_report(report_title, reporter)

Arguments

ReportManager$auto_save_observer()

Usage

ReportManager$auto_save_observer(reporter)

Arguments

ReportManager$unlock_report_public()

Usage

ReportManager$unlock_report_public(report_title)

Arguments

ReportManager$release_lock()

Usage

ReportManager$release_lock(report_title = NULL)

Arguments

ReportManager$setup_csv_download()

Registers the observeEvent that handles CSV download clicks. Call once from moduleServer after initialization.

Usage

ReportManager$setup_csv_download(input)

Arguments

ReportManager$export_tables_to_csv()

Loads the report from disk, extracts all table-type content from each card, converts each to a data.frame and writes it as a CSV file in output_dir. Returns the vector of written file paths, or an empty character vector when no tables are found.

Usage

ReportManager$export_tables_to_csv(report_title, output_dir)

Arguments

Returns

character vector of written file paths. Re-build reports

ReportManager$rebuild_report()

Rebuild reports to include data that has changed. This will replace loaded report cards with new cards, that were rebuilt from a code used to generate these cards.

Usage

ReportManager$rebuild_report(report_title, rp)

Arguments

ReportManager$clone()

The objects of this class are cloneable with this method.

Usage

ReportManager$clone(deep = FALSE)

Arguments

Add a condition to a BlockConditions object

Description

Add a condition to a BlockConditions object

Usage

add_condition(object, variable, operator, value)

Arguments

Value

An updated BlockConditions object with the new condition added.

Add conditions

Description

Add conditions

Usage

## S4 method for signature 'BlockConditions'
add_condition(object, variable, operator, value)

Create Relative risk column

Description

Usage

create_rel_risk_transformator(dataname, column_name, control_group, label_name)

Arguments

Details

This transformator allows the user to select a column and control group from the dataset and create a relative risk column.

Value

teal::teal_transform_module

Examples

app <- teal::init(
  data = teal.data::teal_data(IRIS = iris, code = "IRIS <- iris"),
  modules = teal::modules(
    teal::example_module(
      transformators = list(
        create_rel_risk_transformator("IRIS",
          label_name = "test",
          control_group = "setosa", column_name = "Species"
        )
      )
    )
  )
)
if (interactive()) {
  shiny::shinyApp(app$ui, app$server)
}

Extract Non-Parent Module Labels to YAML

Description

Extracts module labels from a teal modules object, filters out parent modules (grouping containers), and generates a YAML file with the functional modules.

Usage

extract_modules_to_yaml(mods, filepath, verbose = FALSE)

Arguments

Value

Character vector of non-parent module labels

Examples

# Extract modules from mods object to YAML file
mods <- teal::modules(
  teal::example_module("mod1"),
  teal::example_module("mod2")
)
labels <- extract_modules_to_yaml(mods, "panel_str_modules.yml")
unlink("panel_str_modules.yml")

# Clean up
if (file.exists("panel_str_modules.yml")) {
  file.remove("panel_str_modules.yml")
}

View model for or_filtering_transformator().

Description

View model for or_filtering_transformator().

Public fields

Methods

Public methods

• filtering_transformator_model$new()

• filtering_transformator_model$add_alternative()

• filtering_transformator_model$is_duplicate_condition()

• filtering_transformator_model$clone()

filtering_transformator_model$new()

Usage

filtering_transformator_model$new(data, dataname)

Arguments

filtering_transformator_model$add_alternative()

Usage

filtering_transformator_model$add_alternative()

Returns

invisibly self. Checks for duplicate conditions

filtering_transformator_model$is_duplicate_condition()

Usage

filtering_transformator_model$is_duplicate_condition(cond_str, block_cond_list)

Arguments

Returns

logical(1) whether the added condition is a duplicate.

filtering_transformator_model$clone()

The objects of this class are cloneable with this method.

Usage

filtering_transformator_model$clone(deep = FALSE)

Arguments

Change X-axis scaling decorator for teal.modules.clinical::tm_g_forest_rsp.

Description

A function to create a UI component for selecting a transform function for the forest plot x axis.

Usage

forestplot_x_decorator()

Details

The module creates a UI with a radio control for selecting the transform function. The selected transformation function is applied to the forest plot to update the plot's axis and annotations accordingly.

Value

teal::teal_transform_module Returns a modified plot object with the transformation applied.

Examples

library(teal.modules.clinical)
data <- teal.data::teal_data()
data <- within(data, {
  ADSL <- teal.modules.clinical::tmc_ex_adsl
  ADRS <- teal.modules.clinical::tmc_ex_adrs |>
    dplyr::mutate(AVALC = tern::d_onco_rsp_label(AVALC) |>
      formatters::with_label("Character Result/Finding")) |>
    dplyr::filter(PARAMCD != "OVRINV" | AVISIT == "FOLLOW UP")
})
teal.data::join_keys(data) <- teal.data::default_cdisc_join_keys[names(data)]

ADSL <- data[["ADSL"]]
ADRS <- data[["ADRS"]]

arm_ref_comp <- list(
  ARM = list(
    ref = "B: Placebo",
    comp = c("A: Drug X", "C: Combination")
  ),
  ARMCD = list(
    ref = "ARM B",
    comp = c("ARM A", "ARM C")
  )
)

app <- teal::init(
  data = data,
  modules = teal::modules(
    teal.modules.clinical::tm_g_forest_rsp(
      label = "Forest Response",
      dataname = "ADRS",
      arm_var = choices_selected(
        variable_choices(ADSL, c("ARM", "ARMCD")),
        "ARMCD"
      ),
      arm_ref_comp = arm_ref_comp,
      paramcd = choices_selected(
        value_choices(ADRS, "PARAMCD", "PARAM"),
        "INVET"
      ),
      subgroup_var = choices_selected(
        variable_choices(ADSL, names(ADSL)),
        c("BMRKR2", "SEX")
      ),
      strata_var = choices_selected(
        variable_choices(ADSL, c("STRATA1", "STRATA2")),
        "STRATA2"
      ),
      plot_height = c(600L, 200L, 2000L),
      decorators = list(
        plot = forestplot_x_decorator()
      ),
      default_responses = list(
        BESRSPI = list(
          rsp = c("Stable Disease (SD)", "Not Evaluable (NE)"),
          levels = c(
            "Complete Response (CR)", "Partial Response (PR)", "Stable Disease (SD)",
            "Progressive Disease (PD)", "Not Evaluable (NE)"
          )
        ),
        INVET = list(
          rsp = c("Complete Response (CR)", "Partial Response (PR)"),
          levels = c(
            "Complete Response (CR)", "Not Evaluable (NE)", "Partial Response (PR)",
            "Progressive Disease (PD)", "Stable Disease (SD)"
          )
        ),
        OVRINV = list(
          rsp = c("Progressive Disease (PD)", "Stable Disease (SD)"),
          levels = c("Progressive Disease (PD)", "Stable Disease (SD)", "Not Evaluable (NE)")
        )
      )
    )
  )
)
if (interactive()) {
  shinyApp(app$ui, app$server)
}

Create a forest plot from an rtable with x transform settings

Description

Given a rtables::rtable() object with at least one column with a single value and one column with 2 values, converts table to a ggplot2::ggplot() object and generates an accompanying forest plot. The table and forest plot are printed side-by-side.

Usage

g_forest_with_transform(
  tbl,
  col_x = attr(tbl, "col_x"),
  col_ci = attr(tbl, "col_ci"),
  vline = 1,
  forest_header = attr(tbl, "forest_header"),
  xlim = c(0.1, 10),
  transform_x = NA,
  x_at = c(0.1, 1, 10),
  width_columns = NULL,
  lbl_col_padding = 0,
  rel_width_forest = 0.25,
  font_size = 12,
  col_symbol_size = attr(tbl, "col_symbol_size"),
  col = getOption("ggplot2.discrete.colour")[1],
  ggtheme = NULL,
  as_list = FALSE
)

Arguments

Value

ggplot forest plot and table.

Get condition expression

Description

Get condition expression

Usage

get_str_expression(object, dataname, data)

Arguments

Value

character(1) The condition expression.

Get condition expression

Description

Get condition expression

Usage

## S4 method for signature 'BlockConditions'
get_str_expression(object, dataname, data)

ggplot decorator

Description

Decorator function to update various settings for ggplot plot objects

Usage

ggplot_decorator(
  output_name,
  label_text = "decorator",
  render_ui = c(),
  plot_options = list(title = "", footnote = "", y_breaks = "", y_limits_max = "",
    y_limits_min = "", x_breaks = "", x_labels_discrete = "", x_labels_cont = "",
    y_labels_discrete = "", y_labels_cont = "", font_size_geom_text = "",
    font_size_plot_title = "", font_size_axis_title = "", font_size_axis_text = "")
)

Arguments

Details

The module creates a UI with text controls for specifying the list of ggplot options given in the plot_options parameter value. The entered ggplot options are applied to ggplot plot object.

Value

teal::teal_transform_module Returns a modified plot object with the transformation applied.

Examples

data <- teal.data::teal_data()
data <- within(data, {
  ADSL <- teal.data::rADSL
})
teal.data::join_keys(data) <- teal.data::default_cdisc_join_keys[names(data)]

# teal.modules.general >= 0.6.0
app <- teal::init(
  data = data,
  modules = teal::modules(
    teal.modules.general::tm_g_scatterplot(
      label = "Scatterplot Choices",
      x = teal.transform::data_extract_spec(
        dataname = "ADSL",
        select = teal.transform::select_spec(
          label = "Select variable:",
          choices = teal.transform::variable_choices(data[["ADSL"]], c("AGE", "BMRKR1", "BMRKR2")),
          selected = "AGE",
          multiple = FALSE,
          fixed = FALSE
        )
      ),
      y = teal.transform::data_extract_spec(
        dataname = "ADSL",
        select = teal.transform::select_spec(
          label = "Select variable:",
          choices = teal.transform::variable_choices(data[["ADSL"]], c("AGE", "BMRKR1", "BMRKR2")),
          selected = "BMRKR1",
          multiple = FALSE,
          fixed = FALSE
        )
      ),
      decorators = list(
        plot = ggplot_decorator(
          output_name = "plot", render_ui = c("title", "footnote", "font_size_axis_title")
        )
      )
    )
  )
)

if (interactive()) {
  shiny::shinyApp(app$ui, app$server)
}

Filter Teal Modules by Label

Description

Recursively filters a teal modules object to keep only modules whose labels match the specified labels. Removes modules that don't match and empty parent containers.

Usage

keep_by_label(x, label)

Arguments

Value

Filtered teal_modules or teal_module object, or NULL if none matches.

Examples

# Keep only specific modules by label
mods <- teal::modules(
  teal::example_module("mod1"),
  teal::example_module("mod2")
)
filtered_mods <- keep_by_label(mods, c("Data Table", "Disposition"))

Combine levels of a variable into one level

Description

Usage

merge_levels_transformator(dataname, predefined = list())

Arguments

Details

This transformator allows the user to select a column from the dataset and merge levels of this column into a new level. Only selected levels are affected.

Value

teal::teal_transform_module

Examples

app <- teal::init(
  data = teal.data::teal_data(IRIS = iris, code = "IRIS <- iris"),
  modules = teal::modules(
    teal::example_module(
      transformators = list(merge_levels_transformator(
        dataname = "IRIS",
        predefined = list(
          list("Species", "setosa", "SETOSA_WITHIN_FIX"),
          list("Petal.Width", c(0.2, 0.3, 0.5), 12)
        )
      ))
    )
  )
)
if (interactive()) {
  shiny::shinyApp(app$ui, app$server)
}

Apply Logical AND/OR filter transformations

Description

This transformator provides users with flexible, dynamic filtering capabilities for datasets.

Each instance of the transformator operates on a single dataset. Users can define multiple filter blocks, where:

• Conditions within each block are combined with logical AND.

• Multiple blocks are combined with logical OR.

This allows creating complex filter expressions like:

(Condition1 AND Condition2) OR (Condition3 AND Condition4)

To apply filtering across multiple datasets, users can instantiate multiple instances of this module, each configured for a different dataset. Each module call is independent and manages filters for its specific dataset.

• Supported Data Types & Expressions:

  • Supports filtering on character, factor, and numeric columns.

  • Conditions can use operators: ==, !=, <, >, <=, >=, %in%, !%in%.

  • Conditions are specified as simple expressions, e.g., columnA == 'value' columnB != 5 columnC >= 10

  • Each block's conditions are combined with AND.

  • Multiple blocks are combined with OR.

• Features:

  • Add Multiple OR Blocks: Dynamically add new blocks for alternative conditions.

  • Add Conditions: Within each block, add multiple conditions, with duplicate prevention.

  • Preview Filter Expression: Generate and display the current combined filter expression.

  • Remove Conditions: Remove individual conditions within a block.

  • Expression Generation: The resulting expression can be directly used with dplyr::filter() or similar functions.

• Usage Pattern:

  • Call the module multiple times with different dataset names to filter multiple datasets independently.

  • Each call manages its own filter state and expression.

  • Users can build complex filters per dataset and apply or combine them as needed.

Usage

or_filtering_transformator(dataname)

Arguments

Value

teal::teal_transform_module

Examples

app <- teal::init(
  data = teal.data::teal_data(IRIS = iris),
  modules = teal::modules(teal::example_module(
    transformators = list(or_filtering_transformator("IRIS"))
  ))
)
if (interactive()) {
  shinyApp(app$ui, app$server)
}

Patchwork Decorator

Description

Decorator function to add plot title and footnote to patchwork plots

Usage

patchwork_plot_decorator(output_name, label_text = "decorator")

Arguments

Details

The module creates a UI with text controls for plot title and footnote. The entered title and footnote text are applied to the patchwork plots.

Value

(teal.data::qenv) Returns a modified plot object with the transformation applied.

Remove Teal Modules by Label

Description

Recursively removes modules from a teal modules structure that match the specified labels.

Usage

remove_by_label(x, label)

Arguments

Value

The filtered teal modules object with matching modules removed, or NULL if all modules are removed.

Examples

mods <- teal::modules(
  teal::example_module("mod1"),
  teal::example_module("mod2")
)
# Remove a single module
filtered_mods <- remove_by_label(mods, "Deaths")

# Remove multiple modules
filtered_mods <- remove_by_label(mods, c("Deaths", "Lab Summary Table"))

The server part of tm_report_manager().

Description

The server part of tm_report_manager().

Usage

report_manager_server(id, reports_path = "reports", auto_save = TRUE, reporter)

Arguments

The UI of tm_report_manager()

Description

The UI of tm_report_manager()

Usage

report_manager_ui(id)

Arguments

Title and Footer Decorator

Description

A function to create a UI component for selecting a title and footer for tables or plots. It reads title information from a specified Excel file and allows users to choose a title from the provided options. It also provides user with flexibility to customize the title and footer according to their specific needs.

Usage

title_footer_decorator(
  output_name,
  titles_file,
  choices = NULL,
  selected = NULL
)

Arguments

Details

The module creates a UI with a dropdown for selecting a title. Once a title is selected, it updates the output by either adding titles to a table or modifying a plot's title and caption accordingly. Additionally, it includes a checkbox that user can check to enable customization, allowing them to enter their own values for the title and footer in the designated input fields.

Value

teal::teal_transform_module()

See Also

For the exact Excel workbook layout expected by this function, see the package vignette: vignette("title-footer-decorator-excel-structure", package = "uteals")

Examples

library(openxlsx)
library(teal.modules.general)

example_excel <- data.frame(
  `TABLE ID` = c(
    "DO_NOT_DELETE",
    "TSFAE01A", "TSFAE01A", "TSFAE01A",
    "TSFAE01B", "TSFAE01B"
  ),
  IDENTIFIER = c(
    "DO_NOT_DELETE",
    "TITLE", "FOOTNOTE1", "FOOTNOTE2",
    "TITLE", "FOOTNOTE1"
  ),
  TEXT = c(
    "DO_NOT_DELETE",
    "Adverse Events Summary A", "Source: Clinical Study Report", "Confidential",
    "Adverse Events Summary B", "Draft Version"
  ),
  stringsAsFactors = FALSE,
  check.names = FALSE
)

temp_titles <- tempfile(fileext = ".xlsx")
write.xlsx(example_excel, temp_titles, sheetName = "Sheet1", asTable = TRUE)
plot_module <- tm_g_scatterplot(
  label = "Scatter Plot",
  x = data_extract_spec(
    dataname = "IRIS",
    select = select_spec(
      choices = variable_choices(
        "IRIS", c("Sepal.Length", "Sepal.Width")
      ), selected = "Sepal.Length"
    )
  ),
  y = data_extract_spec(
    dataname = "IRIS",
    select = select_spec(
      choices = variable_choices(
        "IRIS", c("Petal.Length", "Petal.Width")
      ), selected = "Petal.Length"
    )
  ),
  decorators = list(
    plot = title_footer_decorator(
      "plot", temp_titles,
      choices = c("TSFAE01A", "TSFAE01B"), selected = NULL
    )
  )
)

# Initialize the teal app
app <- init(
  data = teal_data(IRIS = iris),
  modules = list(plot_module)
)

# Run the app
if (interactive()) {
  shinyApp(app$ui, app$server)
}

Report Manager Module

Description

Report Manager Module

Usage

tm_report_manager(reports_path = "reports", auto_save = TRUE)

Arguments

Details

This module supports collaborative work on teal reports, generated by teal.reporter package. This module extends functionalities of teal.reporter and allows to store reports in chosen path. Reports will be stored as JSON files inside folders named after reports.

Examples

app <- teal::init(
  data = teal.data::teal_data(IRIS = iris),
  modules = teal::modules(
    teal::example_module(transformators = list(or_filtering_transformator("IRIS"))),
    tm_report_manager()
  )
)
if (interactive()) {
  shinyApp(app$ui, app$server)
}

Watermark Decorator

Description

A function to create a UI component for selecting watermark text for plots. Note: Currently tables are not supported

Usage

watermark_decorator(output_name, watermark_text = "", font_size = 90)

Arguments

Details

The module creates a UI with textInput for specifying watermark text and font size. the entered watermark text is displayed with a default gridify layout.

Value

teal::teal_transform_module()