Introduction to shinyCohortBuilder

This document presents to you the functionality offered by shinyCohortBuilder package. You’ll learn here how to apply cohortBuilder into your Shiny application and how filters configuration affects the resulting GUI. Later on, we’ll present what cohortBuilder features can be used in Shiny and what steps can you make to automate cohort configuration.

shinyCohortBuilder vs. cohortBuilder

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

With the approach taken in cohortBuilder:

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:

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

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

  1. 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:

  1. 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: OSNCJ1655974356804
#>    Filter Type: range
#>    Filter Parameters:
#>      dataset: iris
#>      variable: Sepal.Length
#>      range: NA
#>      keep_na: TRUE
#>      description: 
#>      active: TRUE
#> -> Filter ID: RVKET1655974356804
#>    Filter Type: range
#>    Filter Parameters:
#>      dataset: iris
#>      variable: Sepal.Width
#>      range: NA
#>      keep_na: TRUE
#>      description: 
#>      active: TRUE
#> -> Filter ID: NVYZE1655974356804
#>    Filter Type: range
#>    Filter Parameters:
#>      dataset: iris
#>      variable: Petal.Length
#>      range: NA
#>      keep_na: TRUE
#>      description: 
#>      active: TRUE
#> -> Filter ID: SYYIC1655974356804
#>    Filter Type: range
#>    Filter Parameters:
#>      dataset: iris
#>      variable: Petal.Width
#>      range: NA
#>      keep_na: TRUE
#>      description: 
#>      active: TRUE
#> -> Filter ID: HZGJI1655974356804
#>    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:

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.

Multiple-steps filtering

Available with cb_ui(..., steps = TRUE).

The options adds Add Step button to filtering panel and attaches Delete buttons to each filtering step. With the functionality you can perform filtering operations in multiple steps.

By default - newly added filtering step is replicated based on the last available step in the Cohort (with choices and statistics related to the previous step).

The second option allows users to configure newly added steps.

In order to enable this option:

  1. Attach list of available filters as available_filters argument while creating source:
set_source(
  ..., 
  available_filters = list(
    filter("discrete", ...),
    filter("range", ...),
    ...
  )
)
  1. Specify cb_ui(..., new_step = "configure") or gui(..., new_step = "configure") to enable configuration panel.

The available filters can be then chosen in step configuration panel.

Reproducible code

Available with cb_ui(..., code = TRUE).

The option adds Reproducible Code button to filtering panel. When the button is clicked a modal shows up presenting reproducible code for source data filtering.