filter_spec: Data extract filter specification

In teal.transform: Functions for Extracting and Merging Data in the 'teal' Framework

Data extract filter specification

Description

It consists in choices and additionally the variable names for the choices.

Usage

filter_spec(
  vars,
  choices = NULL,
  selected = if (inherits(choices, "delayed_data")) NULL else choices[1],
  multiple = length(selected) > 1 || inherits(selected, "multiple_choices"),
  label = "Filter by",
  sep = attr(choices, "sep"),
  drop_keys = FALSE
)

Arguments

vars	(character or delayed_data) object. Character vector giving the columns to be filtered. These should be key variables of the data set to be filtered. delayed_data objects can be created via variable_choices(), value_choices(), or choices_selected().
choices	(character or numeric or logical or (delayed_data) object. Named character vector to define the choices of a shiny shiny::selectInput(). These choices will be used to filter the dataset. These shall be filter values of the vars input separated by the separator(sep). Please watch out that the filter values have to follow the order of the vars input. In the following example we will show how to filter two columns: vars = c("PARAMCD","AVISIT") and choices = c("CRP - BASELINE", "ALT - BASELINE") will lead to a filtering of (PARAMCD == "CRP" & AVISIT == "BASELINE") | (PARAMCD == "ALT" & AVISIT == "BASELINE"). The sep input has to be " - " in this case. delayed_data objects can be created via variable_choices() or value_choices().
selected	(character or numeric or logical or (delayed_data or delayed_choices) object. Named character vector to define the selected values of a shiny shiny::selectInput() (default values). This value will be displayed inside the shiny app upon start. delayed_choices objects resolve selection when choices become available.
multiple	(logical) Whether multiple values shall be allowed in the shiny shiny::selectInput().
label	(character) optional, defines a label on top of this specific shiny shiny::selectInput(). The default value is "Filter by".
sep	(character) A separator string to split the choices or selected inputs into the values of the different columns.
drop_keys	(logical) optional, whether to drop filter column from the dataset keys, TRUE on default.

Details

The filter_spec is used inside teal apps to allow filtering datasets for their key variables. Imagine having an adverse events table. It has the columns PARAMCD and CNSR. PARAMCD contains the levels "OS", "PFS", "EFS". CNSR contains the levels "0" and "1". The first example should show how a filter_spec setup will influence the drop-down menu the app user will see.

Value

filter_spec-S3-class object or delayed_filter_spec-S3-class object.

Examples

# for Adverse Events table
filter_spec(
  vars = c("PARAMCD", "CNSR"),
  sep = "-",
  choices = c("OS-1" = "OS-1", "OS-0" = "OS-0", "PFS-1" = "PFS-1"),
  selected = "OS-1",
  multiple = FALSE,
  label = "Choose endpoint and Censor"
)

# filtering a single variable
filter_spec(
  vars = c("PARAMCD"),
  sep = "-",
  choices = c("OS", "PFS", "EFS"),
  selected = "OS",
  multiple = FALSE,
  label = "Choose endpoint"
)

# filtering a single variable by multiple levels of the variable
filter_spec(
  vars = c("PARAMCD"),
  sep = "-",
  choices = c("OS", "PFS", "EFS"),
  selected = c("OS", "PFS"),
  multiple = TRUE,
  label = "Choose endpoint"
)

# delayed version
filter_spec(
  vars = variable_choices("ADSL", "SEX"),
  sep = "-",
  choices = value_choices("ADSL", "SEX", "SEX"),
  selected = "F",
  multiple = FALSE,
  label = "Choose endpoint and Censor"
)
# using `choices_selected()`
filter_spec(
  vars = choices_selected(variable_choices("ADSL", subset = c("SEX", "AGE")), "SEX", fixed = FALSE),
  multiple = TRUE
)

filter_spec(
  vars = choices_selected(variable_choices("ADSL"), "SEX", fixed = TRUE),
  multiple = TRUE
)

# choose all choices
adsl_filter <- filter_spec(
  vars = choices_selected(variable_choices("ADSL"), "SEX", fixed = FALSE),
  choices = value_choices("ADSL", "SEX"),
  selected = all_choices()
)

teal.transform documentation built on Aug. 21, 2025, 5:55 p.m.