Introduction to shinyCohortBuilder

shinyCohortBuilder vs. cohortBuilder

When creating cohortBuilder our main goal was to easily allow using its features in Shiny.

With the approach taken in cohortBuilder:

• keeping Cohort objects as an R6 class,
• introduced hooks system

we were able to fully separate cohortBuilder as an operating backend, but also enabled to implement its features to a GUI named shinyCohortBuilder.

The rule of using cohortBuilder and shinyCohortBuilder is simple. With cohortBuilder you create Source and configure Cohort with filtering steps - with shinyCohortBuilder you generate filtering panel in Shiny based on the Cohort.

Cohort to Filtering Panel

When you configure Cohort with the filters you want to see in the panel, use cb_ui and cb_server to place the panel in application UI and run it’s server logic:

library(shiny)
library(cohortBuilder)
library(shinyCohortBuilder)

ui <- fluidPage(
  cb_ui("panel_id")
)

server <- function(input, output, session) {
  source_obj <- set_source(tblist(iris = iris))
  cohort_obj <- cohort(
    source_obj,
    filter("discrete", id = "species", dataset = "iris", variable = "Species"),
    filter("range", id = "petal_length", dataset = "iris", variable = "Petal.Length")
  )
  cb_server("panel_id", cohort_obj)
}

shinyApp(ui, server)

Filter vs Filter Controller

Now let’s highlight how filter parameters affect filter controller in GUI.

1. Filter value as default selection.

When you precise filter value parameter (e.g. value for “discrete” or range for range filter) the value is taken as a initial selection in filter controller.

If you skip providing value (or set is to NA) the initial selection is calculated automatically:

• for discrete and multi_discrete filter all the options are chosen,
• for range, date_range filters the whole available range is selected,
• for discrete_text filter all the available (comma separated) options are chosen.

2. Inactive filter is collapsed.

Whenever you define filter, the one will be enrolled and ready to use by default:

If you want provide the selected filter as the optional one in Shiny, you may set active = FALSE in filter configuration. In GUI, the filter will be collapsed and skipped while computing Cohort data.

From UX (and performance) perspective it’s worth to always collapse all the filters initially.

You may achieve this by setting options("cb_active_filter" = FALSE) before you create filters.

3. Dropdown or checkbox group for discrete filter

By default, discrete filters are transformed for checkbox group input controller. When having multiple options to choose, the approach may become inconvenient.

You may switch from checkbox group to search dropdown (shinyWidgets::virtualSelectInput) with providing gui_input = "vs" parameter to discrete filter.

You can customize the input controller with gui_args argument (see the next section).

4. Slider or numeric input for range filter

For range filters the default input in GUI is connection of slider and numeric range input. You can choose which input to use by providing selected gui_input parameter:

• gui_input = "numeric" - numeric range only,
• gui_input = "slider" - slider only,
• gui_input = c("slider", "numeric") or skipped - both options.

5. Controller configuration

You can customize filter GUI controller with gui_args argument passed to the filter. The argument stores list of parameters that are passed to the function responsible for generating the filter controller.

List of functions that are used for specific filter type:

• "discrete" (default) - shiny::checkboxGroupInput
• "discrete" (gui_input = "vs") - shinyWidgets::virtualSelectInput
• "range" (gui_input = "slider") - shiny::sliderInput
• "range" (gui_input = "numeric") - shinyWidgets::numericRangeInput
• "range" (gui_input = c("slider", "numeric"), default) - arguments are passed to both functions
• "date_range" - shiny::dateRangeInput
• "multi_discrete" - shinyGizmo::pickCheckboxInput
• "discrete_text" - shinyGizmo::textArea

An example is disabling search feature and showing dropdown list at the top of it. You can achieve this with:

filter(type = "discrete", ..., gui_input = "vs", gui_args = list(search = FALSE, position = "top"))

6. Mapping for discrete filter options

It may happen some of the columns are storing key, not readable values to the users. In this case we’d like to replace keys with understandable labels in the input controller.

To achieve the goal you need to create the mapping function taking keys vector as an argument and cohort and returning labels. The function should be then added to Source while its creation using value_mappings argument.

Then pass the function name (as a character) to value_mapping parameter of the filter.

library(shiny)
library(cohortBuilder)
library(shinyCohortBuilder)

program_vm <- function(programs, cohort) {
  c(
    "standard" = "Standard", 
    "premium" = "Premium", 
    "vip" = "VIP"
  )[programs]
}

librarian_source <- set_source(
  as.tblist(librarian),
  value_mappings = list(program_vm = program_vm)
)
librarian_cohort <- cohort(
  librarian_source,
  filter(
    "discrete", 
    id = "program", 
    dataset = "borrowers", 
    variable = "program",
    value_mapping = "program_vm",
    gui_input = "vs"
  )
)

gui(librarian_cohort)

Automatic filters configuration

If you want to skip configuring filters for all of the tables and columns in the source, you may use shinyCohortBuilder::autofilter method.

The method applied on Source, will scan all the columns included in Source and automatically configure proper filters to them. The filters will be stored within a Source, so it’s enough to pass such object to Cohort:

iris_source <- set_source(tblist(iris = iris)) %>% 
  autofilter()
iris_cohort <- cohort(iris_source)

sum_up(iris_cohort)
#> >> Step ID: 1
#> -> Filter ID: OSNCJ1728893052253
#>    Filter Type: range
#>    Filter Parameters:
#>      dataset: iris
#>      variable: Sepal.Length
#>      range: NA
#>      keep_na: TRUE
#>      description: 
#>      active: TRUE
#> -> Filter ID: RVKET1728893052253
#>    Filter Type: range
#>    Filter Parameters:
#>      dataset: iris
#>      variable: Sepal.Width
#>      range: NA
#>      keep_na: TRUE
#>      description: 
#>      active: TRUE
#> -> Filter ID: NVYZE1728893052253
#>    Filter Type: range
#>    Filter Parameters:
#>      dataset: iris
#>      variable: Petal.Length
#>      range: NA
#>      keep_na: TRUE
#>      description: 
#>      active: TRUE
#> -> Filter ID: SYYIC1728893052253
#>    Filter Type: range
#>    Filter Parameters:
#>      dataset: iris
#>      variable: Petal.Width
#>      range: NA
#>      keep_na: TRUE
#>      description: 
#>      active: TRUE
#> -> Filter ID: HZGJI1728893052254
#>    Filter Type: discrete
#>    Filter Parameters:
#>      dataset: iris
#>      variable: Species
#>      value: NA
#>      keep_na: TRUE
#>      description: 
#>      active: TRUE

The autofilter method checks column type and count of levels to apply the proper filter:

• numeric or integer class - range filter,
• factor or character with levels count equal to column length (usually primary keys) - discrete_text filter,
• factor or character with less than 4 levels, or logical column - discrete filter with checkbox group input,
• factor or character with more than 4 levels and more - discrete filter with virtual select input.

Providing custom rules will be added in the future releases of shinyCohortBuilder.

Note. You can use autofilter to attach the generated filters configuration to Source as available_filters attribute. Just use autofilter(..., attach_as = "meta"). See Multiple-steps filters.

cohortBuilder to GUI features

Now we’re gonna highlight what features available in cohortBuilder can be also enabled in GUI panel.

set_source(
  ..., 
  available_filters = list(
    filter("discrete", ...),
    filter("range", ...),
    ...
  )
)