Decorators and transformators for teal modules.

Description

Provides decorator and transformator modules for teal modules.

Author(s)

Maintainer: Konrad Pagacz konrad.pagacz@gmail.com

Authors:

• Nadia Abraham NAbraha5@ITS.JNJ.com

• Chanchal Bhalla CBhalla@ITS.JNJ.com

• Peyman Eshghi peymaan.es@gmail.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

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.

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"))
    )
  )
)
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")

View model for or_filtering_transformator().

Description

View model for or_filtering_transformator().

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()

Method new()

Usage

filtering_transformator_model$new(data, dataname)

Arguments

Method add_alternative()

Usage

filtering_transformator_model$add_alternative()

Returns

invisibly self.

Method 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.

Method 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

app <- teal::init(
  data = teal.data::teal_data(IRIS = iris, code = "IRIS <- iris"),
  modules = teal::modules(
    teal.modules.general::tm_g_scatterplot(
      x = teal.transform::data_extract_spec(
        dataname = "IRIS",
        select = teal.transform::select_spec(choices = teal.transform::variable_choices(iris))
      ),
      y = teal.transform::data_extract_spec(
        dataname = "IRIS",
        select = teal.transform::select_spec(choices = teal.transform::variable_choices(iris))
      ),
      decorators = list(
        plot = ggplot_decorator(
          output_name = "plot", render_ui = c("title", "footnote", "font_size_axis_title")
        )
      )
    )
  )
)
if (interactive()) {
  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)

Arguments

Details

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

The new combined level is called "Combined".

Merging works only for character or factor columns.

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(uteals::merge_levels_transformator("IRIS"))
    )
  )
)
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: ==, !=, <, >, <=, >=.

  • 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"))

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)
}