Package {cohortBuilder}

Create data source cohort

Description

Create data source cohort

Operator simplifying adding steps or filters to Cohort and Source objects

Description

When called with filter or step object, runs add_filter and add_step respectively.

Usage

x %->% object

Arguments

Value

An object ('Source' or 'Cohort') having new filter or step added.

Generate a deterministic filter ID from dataset and variable names.

Description

Generate a deterministic filter ID from dataset and variable names.

Usage

.default_filter_id(dataset, variables, suffix = NULL)

Arguments

Value

A single character string suitable for use as a filter ID.

Generate a default filter display name from its variables.

Description

Single-variable filters are named after their variable. Multi-variable filters get a summarised name listing the first two variables, the count of remaining variables, and the filter type, e.g. '"age sex + 2 vars multi_discrete"'.

Usage

.default_filter_name(variables, type)

Arguments

Value

A single character string suitable for use as a filter name.

Environment storing registered filter type constructors.

Description

Environment storing registered filter type constructors.

Usage

.filter_registry

Format

An object of class environment of length 0.

Generate random ID

Description

Generate random ID

Usage

.gen_id()

Value

A character type value.

Return list of objects matching provided condition.

Description

Return list of objects matching provided condition.

Usage

.get_item(list_obj, attribute, value, operator = `==`)

Arguments

Value

A subset of list object matching provided condition.

Examples

my_list <- list(
  list(id = 1, name = "a"),
  list(id = 2, name = "b")
)
.get_item(my_list, "id", 1)
.get_item(my_list, "name", c("b", "c"), identical)

Get function definition

Description

Whenever the function with provided name exists anywhere, the one is returned (or the first one if multiple found). Return NULL otherwise.

Usage

.get_method(name)

Arguments

Value

Function - when found in any namespace or NULL otherwise.

Return default value if values are equal

Description

Return default value if values are equal

Usage

.if_value(x, value, default)

Arguments

Value

Evaluated condition or provided default value.

Method for printing filter details

Description

Method for printing filter details

Usage

.print_filter(filter, data_objects, to_string = FALSE)

## Default S3 method:
.print_filter(filter, data_objects, to_string = FALSE)

Arguments

Propagate domains between steps

Description

Source-layer generic that recomputes the domains of a **target step** from that step's parent (the previous step). Override to implement dynamic domain narrowing.

Usage

.propagate_domains(source, data_object, step_id, cohort, ...)

## Default S3 method:
.propagate_domains(source, data_object, step_id, cohort, ...)

## S3 method for class 'tblist'
.propagate_domains(source, data_object, step_id, cohort, mode, ...)

Arguments

Details

The default is a no-op. Only called when 'propagate_domains != "none"' in the Cohort.

Contract: ‘step_id = N' recomputes the domains of step 'N'’s filters using step 'N - 1' as the source of truth. It is a no-op when 'N' has no parent (i.e. 'N == "1"') or when the target step is absent.

Base class for all cohortBuilder filters

Description

Base class for all cohortBuilder filters

Usage

CbFilter(
  type = character(0),
  id = character(0),
  name = character(0),
  active = logical(0),
  description = NULL,
  domain = NULL,
  step_id = NULL,
  extra = list(),
  private = list()
)

Arguments

Date range filter class

Description

Filters data by a date range.

Usage

CbFilterDateRange(
  id = NULL,
  name = NULL,
  variable,
  range = NA,
  dataset,
  keep_na = TRUE,
  description = NULL,
  domain = NULL,
  active = getOption("cb_active_filter", default = TRUE),
  ...
)

Arguments

Datetime range filter class

Description

Filters data by a datetime (POSIXct) range.

Usage

CbFilterDatetimeRange(
  id = NULL,
  name = NULL,
  variable,
  range = NA,
  dataset,
  keep_na = TRUE,
  description = NULL,
  domain = NULL,
  active = getOption("cb_active_filter", default = TRUE),
  ...
)

Arguments

Discrete filter class

Description

Filters data by matching a variable against a set of discrete values.

Usage

CbFilterDiscrete(
  id = NULL,
  name = NULL,
  variable,
  value = NA,
  dataset,
  keep_na = TRUE,
  description = NULL,
  domain = NULL,
  active = getOption("cb_active_filter", default = TRUE),
  ...
)

Arguments

Discrete text filter class

Description

Filters data by matching a variable against comma-separated text values.

Usage

CbFilterDiscreteText(
  id = NULL,
  name = NULL,
  variable,
  value = NA,
  dataset,
  keep_na = TRUE,
  description = NULL,
  domain = NULL,
  active = getOption("cb_active_filter", default = TRUE),
  ...
)

Arguments

Multi-discrete filter class

Description

Filters data by matching multiple variables against sets of discrete values.

Usage

CbFilterMultiDiscrete(
  id = NULL,
  name = NULL,
  values,
  variables,
  dataset,
  keep_na = TRUE,
  description = NULL,
  domain = NULL,
  active = getOption("cb_active_filter", default = TRUE),
  ...
)

Arguments

Query filter class

Description

Filters data using a queryBuilder query object.

Usage

CbFilterQuery(
  id = NULL,
  name = NULL,
  variables,
  value = NA,
  dataset,
  keep_na = TRUE,
  description = NULL,
  domain = NULL,
  active = getOption("cb_active_filter", default = TRUE),
  ...
)

Arguments

Range filter class

Description

Filters data by a numeric range.

Usage

CbFilterRange(
  id = NULL,
  name = NULL,
  variable,
  range = NA,
  dataset,
  keep_na = TRUE,
  description = NULL,
  domain = NULL,
  active = getOption("cb_active_filter", default = TRUE),
  ...
)

Arguments

R6 class representing Cohort object.

Description

R6 class representing Cohort object.

R6 class representing Cohort object.

Details

Cohort object is designed to make operations on source data possible.

Public fields

Methods

Public methods

• Cohort$new()

• Cohort$add_source()

• Cohort$update_source()

• Cohort$get_source()

• Cohort$get_propagate_domains_mode()

• Cohort$add_step()

• Cohort$copy_step()

• Cohort$remove_step()

• Cohort$add_filter()

• Cohort$remove_filter()

• Cohort$update_filter()

• Cohort$clear_filter()

• Cohort$clear_step()

• Cohort$sum_up_state()

• Cohort$get_state()

• Cohort$restore()

• Cohort$get_data()

• Cohort$plot_data()

• Cohort$show_attrition()

• Cohort$calc_stats()

• Cohort$show_help()

• Cohort$get_code()

• Cohort$run_flow()

• Cohort$run_step()

• Cohort$bind_data()

• Cohort$describe_state()

• Cohort$get_step()

• Cohort$get_filter()

• Cohort$update_stats()

• Cohort$get_stats()

• Cohort$list_active_filters()

• Cohort$last_step_id()

• Cohort$is_pending()

• Cohort$set_pending()

• Cohort$set_pending_cascade()

• Cohort$set_domain()

• Cohort$propagate_domains_to()

• Cohort$propagate_filter_domains()

• Cohort$modify()

• Cohort$clone()

Method new()

Create Cohort object.

Usage

Cohort$new(
  source,
  ...,
  run_flow = FALSE,
  compute_stats = TRUE,
  propagate_domains = c("none", "filter", "stats", "data"),
  hook = list(pre = get_hook("pre_cohort_hook"), post = get_hook("post_cohort_hook"))
)

Arguments

Returns

The object of class 'Cohort'.

Method add_source()

Add Source to Cohort object.

Usage

Cohort$add_source(source)

Arguments

Method update_source()

Update Source in the Cohort object.

Usage

Cohort$update_source(
  source,
  keep_steps = !has_steps(source),
  run_flow = FALSE,
  hook = list(pre = get_hook("pre_update_source_hook"), post =
    get_hook("post_update_source_hook"))
)

Arguments

Method get_source()

Return Source object attached to Cohort.

Usage

Cohort$get_source()

Method get_propagate_domains_mode()

Return the configured domain propagation mode.

One of '"none"', '"filter"', '"stats"' or '"data"'. Read-only; the mode is fixed at construction. UI layers can inspect it (e.g. to validate that a domain-based rendering strategy is compatible with the cohort).

Usage

Cohort$get_propagate_domains_mode()

Method add_step()

Add filtering step definition

Usage

Cohort$add_step(
  step,
  run_flow = FALSE,
  hook = list(pre = get_hook("pre_add_step_hook"), post = get_hook("post_add_step_hook"))
)

Arguments

Method copy_step()

Copy selected step.

Usage

Cohort$copy_step(step_id, filters, run_flow = FALSE)

Arguments

Method remove_step()

Remove filtering step definition

Usage

Cohort$remove_step(
  step_id,
  run_flow = FALSE,
  hook = list(pre = get_hook("pre_rm_step_hook"), post = get_hook("post_rm_step_hook"))
)

Arguments

Method add_filter()

Add filter definition

Usage

Cohort$add_filter(
  filter,
  step_id,
  run_flow = FALSE,
  hook = list(pre = get_hook("pre_add_filter_hook"), post =
    get_hook("post_add_filter_hook"))
)

Arguments

Method remove_filter()

Remove filter definition

Usage

Cohort$remove_filter(
  step_id,
  filter_id,
  run_flow = FALSE,
  hook = list(pre = get_hook("pre_rm_filter_hook"), post =
    get_hook("post_rm_filter_hook"))
)

Arguments

Method update_filter()

Update filter definition

Usage

Cohort$update_filter(
  step_id,
  filter_id,
  ...,
  active,
  run_flow = FALSE,
  hook = list(pre = get_hook("pre_update_filter_hook"), post =
    get_hook("post_update_filter_hook")),
  hook_args = list(pre = list(), post = list())
)

Arguments

Method clear_filter()

Reset filter to its default values.

Usage

Cohort$clear_filter(step_id, filter_id, run_flow = FALSE)

Arguments

Method clear_step()

Reset all filters included in selected step.

Usage

Cohort$clear_step(step_id, run_flow = FALSE)

Arguments

Method sum_up_state()

Sum up Cohort configuration - Source, steps definition and evaluated data.

Usage

Cohort$sum_up_state()

Method get_state()

Get Cohort configuration state.

Usage

Cohort$get_state(step_id, json = FALSE)

Arguments

Method restore()

Usage

Cohort$restore(
  state,
  modifier = function(prev_state, state) state,
  run_flow = FALSE,
  hook = list(pre = get_hook("pre_restore_hook"), post = get_hook("post_restore_hook"))
)

Arguments

Method get_data()

Get step related data

Usage

Cohort$get_data(step_id, state = "post", collect = TRUE)

Arguments

Method plot_data()

Plot filter specific data summary.

Usage

Cohort$plot_data(step_id, filter_id, ..., state = "post")

Arguments

Method show_attrition()

Show attrition plot.

Usage

Cohort$show_attrition(..., percent = FALSE)

Arguments

Method calc_stats()

Get Cohort related statistics.

Usage

Cohort$calc_stats(step_id, filter_id, ..., state = "post")

Arguments

Method show_help()

Show source data or filter description

Usage

Cohort$show_help(
  field,
  step_id,
  filter_id,
  modifier = getOption("cb_help_modifier", default = function(x) x)
)

Arguments

Method get_code()

Return reproducible data filtering code.

Usage

Cohort$get_code(
  include_source = TRUE,
  include_methods = c(".pre_filtering", ".post_filtering", ".run_binding"),
  include_action = c("pre_filtering", "post_filtering", "run_binding"),
  modifier = .repro_code_tweak,
  mark_step = TRUE,
  ...
)

Arguments

Method run_flow()

Trigger data calculations sequentially.

Usage

Cohort$run_flow(
  min_step,
  hook = list(pre = get_hook("pre_run_flow_hook"), post = get_hook("post_run_flow_hook"))
)

Arguments

Method run_step()

Trigger data calculations for selected step.

Usage

Cohort$run_step(
  step_id,
  hook = list(pre = get_hook("pre_run_step_hook"), post = get_hook("post_run_step_hook"))
)

Arguments

Method bind_data()

Run data binding for selected step. See more at binding-keys.

Usage

Cohort$bind_data(step_id)

Arguments

Method describe_state()

Print defined steps configuration.

Usage

Cohort$describe_state(to_string = FALSE)

Arguments

Method get_step()

Get selected step configuration.

Usage

Cohort$get_step(step_id)

Arguments

Method get_filter()

Get selected filter configuration.

Usage

Cohort$get_filter(step_id, filter_id, method = function(x) x)

Arguments

Method update_stats()

Update filter or step statistics. Computes and stores step and filter attached data statistics such as number of data rows, filter choices or frequencies.

Usage

Cohort$update_stats(step_id, filter_id, state = "post", name = NULL)

Arguments

Method get_stats()

Return step or filter specific statistics.

Usage

Cohort$get_stats(
  step_id,
  filter_id,
  state = "post",
  .recalc_when_missing = TRUE,
  name = NULL
)

Arguments

Method list_active_filters()

List active filters included in selected step.

Usage

Cohort$list_active_filters(step_id)

Arguments

Method last_step_id()

Return id of the last existing step in Cohort.

Usage

Cohort$last_step_id()

Method is_pending()

Check if step is pending.

Usage

Cohort$is_pending(step_id)

Arguments

Method set_pending()

Mark step as pending or resolved.

Usage

Cohort$set_pending(
  step_id,
  pending = TRUE,
  hook = list(pre = get_hook("pre_set_pending_hook"), post =
    get_hook("post_set_pending_hook"))
)

Arguments

Method set_pending_cascade()

Mark a step and all the steps after it as pending.

A change to step ‘step_id'’s filters invalidates that step and every step downstream (each step's input is the previous step's output). Used by the filter/step mutating methods so the GUI greys all affected steps via the 'post_set_pending_hook'.

Usage

Cohort$set_pending_cascade(step_id)

Arguments

Method set_domain()

Silently set a filter's domain.

Internal setter used by domain propagation (.propagate_domains). Writes 'filter@domain' directly **without** firing the 'update_filter' hooks and **without** triggering 'run_flow', which prevents the per-hop hook re-entry that would otherwise occur if domains were applied through 'update_filter'. Does not itself trigger further propagation.

Usage

Cohort$set_domain(step_id, filter_id, domain)

Arguments

Method propagate_domains_to()

Recompute a target step's domains from its parent and signal the change.

Thin wrapper around .propagate_domains that runs propagation for ‘target_id' (computing its filters’ domains from step 'target_id - 1') and then fires 'post_propagate_domains_hook' so UI layers can refresh the affected step's inputs. No-op when propagation is disabled or the target step is absent / has no parent.

Usage

Cohort$propagate_domains_to(
  target_id,
  hook = get_hook("post_propagate_domains_hook")
)

Arguments

Method propagate_filter_domains()

Eagerly propagate '"filter"'-mode domains to a target step and all steps after it.

'"filter"' mode needs no computed data, so domains can be (re)established immediately when the step structure changes. Because each step's domain depends on every previous step, this recomputes 'from_target' and cascades downstream ascending. No-op unless the propagation mode is '"filter"'.

Usage

Cohort$propagate_filter_domains(from_target)

Arguments

Method modify()

Helper method enabling to run non-standard operation on Cohort object.

Usage

Cohort$modify(modifier)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Cohort$clone(deep = FALSE)

Arguments

R6 class representing a data source

Description

R6 class representing a data source

R6 class representing a data source

Details

Source is an object storing information about data source such as source type, primary keys and relations between stored data.

Public fields

Active bindings

Methods

Public methods

• Source$new()

• Source$get()

• Source$get_steps()

• Source$add_step()

• Source$rm_step()

• Source$add_filter()

• Source$rm_filter()

• Source$update_filter()

• Source$calc_meta_stats()

• Source$clone()

Method new()

Create a new 'Source' object.

Usage

Source$new(
  dtconn,
  ...,
  primary_keys = NULL,
  binding_keys = NULL,
  source_code = NULL,
  description = NULL,
  available_filters = NULL,
  compute_meta_stats = getOption("cb.source_filters_meta_stats", TRUE),
  options = list(display_binding = TRUE)
)

Arguments

Returns

A new 'Source' object of class 'Source' (and 'dtconn' object class appended).

Method get()

Get selected 'Source' object 'attribute'.

Usage

Source$get(param)

Arguments

Method get_steps()

Returns filtering steps definition, if defined for 'Source'.

Usage

Source$get_steps()

Method add_step()

Add filtering step definition.

Usage

Source$add_step(step)

Arguments

Method rm_step()

Remove filtering step definition.

Usage

Source$rm_step(step_id)

Arguments

Method add_filter()

Add filter definition to selected step.

Usage

Source$add_filter(filter, step_id)

Arguments

Method rm_filter()

Remove filter definition from selected step.

Usage

Source$rm_filter(step_id, filter_id)

Arguments

Method update_filter()

Update filter definition.

Usage

Source$update_filter(step_id, filter_id, ...)

Arguments

Method calc_meta_stats()

Calculate metadata statistics for available filters.

Usage

Source$calc_meta_stats()

Method clone()

The objects of this class are cloneable with this method.

Usage

Source$clone(deep = FALSE)

Arguments

Add filter definition

Description

Add filter definition

Usage

add_filter(x, filter, step_id, ...)

## S3 method for class 'Cohort'
add_filter(
  x,
  filter,
  step_id,
  run_flow = FALSE,
  hook = list(pre = get_hook("pre_add_filter_hook"), post =
    get_hook("post_add_filter_hook")),
  ...
)

## S3 method for class 'Source'
add_filter(x, filter, step_id, ...)

Arguments

Value

Method dependent object (i.e. 'Cohort' or 'Source') having filter added in selected step.

See Also

managing-cohort, managing-source

Add source to Cohort object.

Description

When Cohort object has been created without source, the method allows to attach it.

Usage

add_source(x, source)

Arguments

Value

The 'Cohort' class object with 'Source' attached to it.

See Also

managing-cohort

Add filtering step definition

Description

Add filtering step definition

Usage

add_step(x, step, ...)

## S3 method for class 'Cohort'
add_step(
  x,
  step,
  run_flow = FALSE,
  hook = list(pre = get_hook("pre_add_step_hook"), post = get_hook("post_add_step_hook")),
  ...
)

## S3 method for class 'Source'
add_step(x, step, ...)

Arguments

Value

Method dependent object (i.e. 'Cohort' or 'Source') having new step added.

See Also

managing-cohort, managing-source

Show attrition plot.

Description

Show attrition plot.

Usage

attrition(x, ..., percent = FALSE)

Arguments

Value

Plot object of class 'ggplot'.

See Also

cohort-methods

Generate filters definition based on the Source data

Description

The method should analyze source data structure, generate proper filters based on the data (e.g. column types) and attach them to source.

Usage

autofilter(source, attach_as = c("step", "meta"), ...)

## Default S3 method:
autofilter(source, ...)

## S3 method for class 'tblist'
autofilter(source, attach_as = c("step", "meta"), ...)

Arguments

Value

Source object having step configuration attached.

Examples

library(cohortBuilder)

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

Describe data relations with binding keys

Description

When source consists of multiple datasets, binding keys allow to define what relations occur between them. When binding keys are defined, applying filtering on one dataset may result with updating (filtering) the other ones.

For example having two tables in Source: 'book(book_id, author_id, title)' 'authors(author_id, name, surname)' if we filter 'authors' table, we way want to return only books for the selected authors.

With binding keys you could achieve it by providing 'binding_keys' parameter for Source as below:

  binding_keys = bind_keys(
    bind_key(
      update = data_key('books', 'author_id'),
      data_key('authors', 'author_id')
    )
  )

Or if we want to have two-way relation, just define another binding key:

  binding_keys = bind_keys(
    bind_key(
      update = data_key('books', 'author_id'),
      data_key('authors', 'author_id')
    ),
    bind_key(
      update = data_key('authors', 'author_id'),
      data_key('books', 'author_id')
    )
  )

As a result, whenever 'books' or 'authors' is filtered, the other table will be updated as well.

In order to understand binding keys concept we need to describe the following functions:

• data_key - Defines which table column should be used to describe relation.

• bind_key - Defines what relation occur between datasets.

• bind_keys - If needed, allows to define more than one relation.

- 'data_key' - requires to provide two parameters:

• dataset - Name of the dataset existing in Source.

• key - Single character string or vector storing column names that are keys, which should be used to describe relation.

For example ‘data_key(’books', 'author_id')'.

- 'bind_key' - requires to provide two obligatory parameters

• update - Data key describing which table should be updated.

• ... - Triggering data keys. One or more data keys describing on which dataset(s) the one in 'update' is dependent.

The output of 'bind_key' function is named binding key. 'bind_key' offers two extra parameters 'post' and 'activate'. See below to learn how these parameters affect the final result.

- 'bind_keys' - takes only binding keys as parameters The function is used to define 'binding_keys' parameter of Source. Whenever you define a single or more binding keys wrap them with 'bind_keys'.

It's worth to mention that binding key describes inner-join like relation. That means the updated table's key is intersection of its key and keys of remaining tables defined in binding key.

Another important note is that binding keys order matters - binding is performed sequentially, taking into account returned data from the previous bindings.

You may achieve more flexibility with two parameters:

• activate

• post

Active tables and 'activate' parameter

We name a table 'active' that is attached to at least one active filter (in a step).

When having defined binding key, e.g.

  bind_key(
    update = data_key('books', 'author_id'),
    data_key('authors', 'author_id')
  )

the key is taken into account only when at least one triggering table is active. So in the above example binding key will update 'books' only when 'authors' was filtered (more precisely when any filter attached to 'authors' is active).

The 'activate = TRUE' parameter setup, lets us to decide whether 'update' table should be marked as active as well when the binding finish. This allows to build dependency chains between table.

Let's explain this in the below example. Having defined another table in Source 'borrowed(book_id, user_id, date)' and binding key:

  bind_keys(
    bind_key(
      update = data_key('books', 'book_id'),
      data_key('borrowed', 'book_id')
    ),
    bind_key(
      update = data_key('authors', 'author_id'),
      data_key('books', 'author_id')
    )
  )

Let's consider the case when table 'borrowed' is active, 'books' is not. What happens during the binding process: 1. Based on the first binding key, active 'borrowed' triggers this one. 2. As a result 'books' is modified.

What should happen with the second binding key. We have two options: 1. 'books' could be marked as active as well so it triggers the second key. 2. 'books' could remain inactive so the second key is not triggered. It will be triggered only when 'books' is directly filtered (activated).

You may choose between 1 and 2 with 'activate = TRUE' (the default) and 'activate = FALSE' respectively.

So in the above example (because 'activate = TRUE' by default) the authors table will also be modified by the second binding key.

To turn off this behavior we just need to:

  bind_keys(
    bind_key(
      update = data_key('books', 'book_id'),
      data_key('borrowed', 'book_id'),
      activate = TRUE
    ),
    bind_key(
      update = data_key('authors', 'author_id'),
      data_key('books', 'author_id')
    )
  )

Bind filtered on unfiltered data - 'post' parameter

Let's tart with the below binding key example:

  bind_keys(
    bind_key(
      update = data_key('authors', 'author_id'),
      data_key('books', 'author_id')
    )
  )

Let's assume 'authors' table is filtered and we apply filtering for 'books' table. We may want to achieve one of the two results: 1. 'authors' filters should be taken into account while binding. 2. we should take unfiltered 'authors' an apply binding based on 'books' choices.

We can achieve 1 and 2 with defining 'post = TRUE' (the default) and 'post = FALSE' respectively.

So the following setup:

  bind_keys(
    bind_key(
      update = data_key('authors', 'author_id'),
      data_key('books', 'author_id'),
      post = FALSE
    )
  )

Whenever 'books' is changed will result with filtering only the authors that written selected books - no extra 'authors' filters will be applied.

There might be the situation when table was already bound but there is another one binding key to be executed on the same table.

In this case 'post = FALSE' case will remain the same - unfiltered table will be taken. More to that filtering and previous binding related to this table will be ignored. In case of 'post = TRUE' the previously bound table will be updated.

Usage

bind_keys(...)

bind_key(update, ..., post = TRUE, activate = TRUE)

Arguments

Value

List of class 'bind_keys' storing 'bind_key' class objects ('bind_keys') or 'bind_key' class list ('bind_key').

Extract domain from data

Description

Derives a domain (set of valid values) directly from the data object. Uses dual dispatch on filter type and source type. Custom filter types should implement S7 methods for this generic. The default method returns 'NULL' (no domain).

Usage

cb_domain_from_data(filter, source, ...)

Arguments

Value

Domain value appropriate for the filter type, or 'NULL'.

Extract domain from stored filter statistics

Description

Derives a domain (set of valid values) from previously computed filter statistics. Custom filter types should implement an S7 method for this generic. The default method returns 'NULL' (no domain).

Usage

cb_domain_from_stats(filter, ...)

Arguments

Value

Domain value appropriate for the filter type, or 'NULL'.

Apply filter to data object

Description

Apply filter to data object

Usage

cb_filter_data(filter, source, ...)

Arguments

Value

Filtered data object.

Generate reproducible code expression for filter

Description

Generate reproducible code expression for filter

Usage

cb_filter_to_expr(filter, source, ...)

Arguments

Value

An R expression representing the filter operation.

Get filter-related data

Description

Get filter-related data

Usage

cb_get_filter_data(filter, source, ...)

Arguments

Value

Filter-related data subset.

Get filter default values

Description

Get filter default values

Usage

cb_get_filter_defaults(filter, source, ...)

Arguments

Value

Named list of default parameter values.

Get filter statistics

Description

Get filter statistics

Usage

cb_get_filter_stats(filter, source, ...)

Arguments

Value

List of statistics.

Get effective filter value after domain intersection

Description

Returns the filter's value intersected with its domain. When value is 'NA' and domain is set, returns the domain as the effective value.

Usage

cb_intersect_domain(filter, ...)

Arguments

Details

Custom filter types should implement an S7 method for this generic. The default method returns the raw value with no domain logic.

Value

The effective value for filtering.

Intersect two domain values for a filter type

Description

Combines two already-computed domain values (not value-vs-domain) into their intersection, dispatching on filter type. Used by '"filter"'-mode domain propagation when the same logical filter appears in more than one upstream step and its effective domains must be combined. Unlike [cb_intersect_domain()], this never emits trimming messages.

Usage

cb_intersect_domain_values(filter, ...)

Arguments

Value

The intersected domain value, or 'NULL'.

Plot filter data

Description

Plot filter data

Usage

cb_plot_filter_data(filter, source, ...)

Arguments

Value

Plot side effect.

Register cohortBuilder tools with an ellmer chat

Description

cb_register_tool registers a single cb_tool with an ellmer chat object. cb_register_tools is a convenience wrapper that registers all built-in tools at once.

Usage

cb_register_tool(chat, tool)

cb_register_tools(chat, cohort)

Arguments

Value

The chat object, invisibly (for piping).

Examples

## Not run: 
source <- set_source(tblist(iris = iris)) |> autofilter(attach_as = "meta")
coh <- cohort(source)
chat <- ellmer::chat_openai()
chat |> cb_register_tools(coh)
chat$chat("Show me the available filters")

## End(Not run)

Create a cohortBuilder tool definition

Description

Constructs a tool object that can be registered with an LLM chat via cb_register_tool.

Usage

cb_tool(fun, name, description, arguments = list())

## S3 method for class 'cb_tool'
print(x, ...)

Arguments

Value

An object of class cb_tool.

Create a tool for adding filters to a cohort

Description

Returns a cb_tool that adds selected filters from the source's available_filters to the cohort. The LLM chooses whether to add to a new step or the existing last step via the action argument.

Usage

cb_tool_add_filters(cohort)

Arguments

Value

A cb_tool object.

Create a tool that adds filters and sets their values in one call

Description

Returns a cb_tool that combines filter addition and value assignment into a single tool call. This avoids issues with LLMs splitting the work across multiple parallel calls.

Usage

cb_tool_apply_filters(cohort)

Arguments

Value

A cb_tool object.

Create a tool for resetting filters to defaults

Description

Returns a cb_tool that resets filter values to their defaults without removing the filters from the cohort.

Usage

cb_tool_clear_filters(cohort)

Arguments

Value

A cb_tool object.

Create a tool returning the current cohort state

Description

Returns a cb_tool whose function takes no arguments and returns a structured text summary of all steps, filters, their active status, and pending state.

Usage

cb_tool_describe_state(cohort)

Arguments

Value

A cb_tool object.

Create a tool returning available filters metadata

Description

Returns a cb_tool whose function takes no arguments and returns a JSON string with filter metadata from shape.

Usage

cb_tool_filters_meta(cohort)

Arguments

Value

A cb_tool object.

Create a tool returning reproducible filtering code

Description

Returns a cb_tool that generates reproducible R code for the current cohort filtering pipeline via get_code().

Usage

cb_tool_get_code(cohort)

Arguments

Value

A cb_tool object.

Create a tool returning row counts per dataset and step

Description

Returns a cb_tool that reports how many rows remain in each dataset at each step (before and after filtering). This is the primary tool for understanding the impact of applied filters.

Usage

cb_tool_get_data_summary(cohort)

Arguments

Value

A cb_tool object.

Create a tool for removing filters from the cohort

Description

Returns a cb_tool that removes filters from a step in the cohort. If removing all filters from a step, the entire step is removed.

Usage

cb_tool_remove_filters(cohort)

Arguments

Value

A cb_tool object.

Create a tool for removing the last step

Description

Returns a cb_tool that removes the last step from the cohort, including all its filters.

Usage

cb_tool_remove_step(cohort)

Arguments

Value

A cb_tool object.

Create a tool for running the cohort pipeline

Description

Returns a cb_tool that triggers data calculations for the entire cohort or a specific step. Only functional when the cb_tool_run_cohort option is FALSE; otherwise returns an informative message that the cohort runs automatically.

Usage

cb_tool_run(cohort)

Arguments

Value

A cb_tool object.

Create a tool for setting filter values

Description

Returns a cb_tool that updates filter parameter values on the last step of the cohort and triggers the data pipeline.

Usage

cb_tool_set_filter_values(cohort)

Arguments

Value

A cb_tool object.

Create a tool for activating or deactivating filters

Description

Returns a cb_tool that toggles the active state of existing filters in the cohort.

Usage

cb_tool_toggle_filters(cohort)

Arguments

Value

A cb_tool object.

Return reproducible data filtering code.

Description

Return reproducible data filtering code.

Usage

code(
  x,
  include_source = TRUE,
  include_methods = c(".pre_filtering", ".post_filtering", ".run_binding"),
  include_action = c("pre_filtering", "post_filtering", "run_binding"),
  modifier = .repro_code_tweak,
  mark_step = TRUE,
  ...
)

Arguments

Value

tidy_source output storing reproducible code for generating final step data.

See Also

cohort-methods

Cohort related methods

Description

The list of methods designed for getting Cohort-related details.

• plot_data - Plot filter related Cohort data.

• stat - Get Cohort related statistics.

• code - Return reproducible data filtering code.

• get_data - Get step related data.

• sum_up - Sum up Cohort state.

• get_state - Save Cohort state.

• restore - Restore Cohort state.

• attrition - Show attrition plot.

• description - Show Source or filter related description.

Value

Various type outputs dependent on the selected method. See each method documentation for details.

Create new 'Cohort' object

Description

Cohort object is designed to make operations on source data possible.

Usage

cohort(
  source,
  ...,
  run_flow = FALSE,
  compute_stats = TRUE,
  propagate_domains = c("none", "filter", "stats", "data"),
  hook = list(pre = get_hook("pre_cohort_hook"), post = get_hook("post_cohort_hook"))
)

Arguments

Value

The object of class 'Cohort'.

Define Source dataset key

Description

Data keys are used to define primary_keys and binding-keys.

Usage

data_key(dataset, key)

Arguments

Value

'data_key' class list of two objects: 'dataset' and 'key' storing name and vector of data key names respectively.

Create a description object

Description

Helper for building structured description entries used in source definition.

Usage

describe(description, label = NULL, ...)

Arguments

Value

A named list with 'text', an optional 'label', and any extra parameters.

Show source data or filter description

Description

If defined allows to check the provided description related to source data or configured filters.

Usage

description(
  x,
  field,
  step_id,
  filter_id,
  modifier = getOption("cb_help_modifier", default = function(x) x)
)

Arguments

Value

Any object (or its subset) attached to Source of filter via description argument.

See Also

cohort-methods

Define Cohort filter

Description

Creates an S7 filter object of the specified type.

Usage

filter(type, ...)

Arguments

Value

An S7 filter object inheriting from 'CbFilter'.

Get a filter's domain

Description

Returns the declared domain (universe of valid values) attached to a filter, or 'NULL' when no domain is set. This is a thin accessor over the 'domain' property, intended for downstream consumers (e.g. GUIs) that render filter inputs from the domain without reaching into S7 internals.

Usage

filter_domain(filter)

Arguments

Value

The filter's domain, or 'NULL' when unset. Structure depends on the filter type (e.g. a character vector for discrete filters, a two-element vector for range filters).

See Also

[filter_effective_value()], [cb_intersect_domain()]

Get a filter's effective value

Description

Returns the value that should be used to pre-select the filter input, accounting for the domain. This is the filter's value intersected with its domain; when the value is unset ('NA') and a domain is present, the domain is returned as the effective value. Thin wrapper over [cb_intersect_domain()] for use by GUIs.

Usage

filter_effective_value(filter)

Arguments

Value

The effective value for the filter, suitable for pre-selecting an input. Structure depends on the filter type.

See Also

[filter_domain()], [cb_intersect_domain()]

Get the variables a filter operates on

Description

Returns the column name(s) a filter is bound to, regardless of whether the filter stores them in a single-variable property ('variable') or a multi-variable property ('variables').

Usage

filter_variables(filter)

Arguments

Value

Character vector of variable (column) names. Empty when the filter declares no variables.

Get step related data

Description

Get step related data

Usage

get_data(x, step_id, state = "post", collect = FALSE)

Arguments

Value

Subset of Source-specific data connection object or its evaluated version.

See Also

cohort-methods

Get filter parameters as a list

Description

Extracts all user-facing properties from an S7 filter object.

Usage

get_filter_params(filter, name)

Arguments

Value

Named list of filter parameters, or a single value if 'name' is given. Properties stored in 'filter@private' are always excluded.

Get Cohort configuration state.

Description

Get Cohort configuration state.

Usage

get_state(x, step_id, json = FALSE)

Arguments

Value

List object of character string being the list conversion to JSON format.

See Also

cohort-methods

Cohort hooks.

Description

In order to make integration of 'cohortBuilder' package with other layers/packages easier, hooks system was introduced.

Usage

add_hook(name, method)

get_hook(name)

Arguments

Details

Many Cohort methods allow to define 'hook' parameter. For such method, 'hook' is a list containing two values: 'pre' and 'post', storing functions (hooks) executed before and after the method is run respectively.

Each 'hook' is a function of two obligatory parameters:

• public - Cohort object.

• private - Private environment of Cohort object.

When Cohort method, for which hook is defined, allow to pass custom parameters, the ones should be also available in hook definition (with some exclusions, see below).

For example 'Cohort$remove_step' has three parameters:

• step_id

• run_flow

• hook

By the implementation, the parameters that we should skip are 'run_flow' and 'hook', so the hook should have three parameters 'public', 'private' and 'step_id'.

There are two ways of defining hooks for the specific method. The first one is to define the method 'hook' directly as its parameter (while calling the method).

The second option can be achieved with usage of 'add_hook' (and 'get_hook') function. The default 'hook' parameter for each method is constructed as below:

remove_step = function(step_id, run_flow = FALSE,
  hook = list(
    pre = get_hook("pre_rm_step_hook"),
    post = get_hook("post_rm_step_hook")
  )
)

'Pre' hooks are defined with 'pre_<method_name>_hook' and 'Post' ones as 'post_<method_name>_hook'. As a result calling:

add_hook(
  "pre_remove_step_hook",
  function(public, private, step_id) {...}
)

will result with specifying a new pre-hook for 'remove_step' method.

You may add as many hooks as you want. The order of hooks execution is followed by the order or registering process. If you want to check currently registered hooks for the specific method, just use:

get_hook("pre_<method_name>_hook")

Value

No returned value ('add_hook') or the list of functions ('get_hook').

Sample of library database

Description

A list containing four data frames reflecting library management database.

Usage

librarian

Format

A list of four data frames:

books - books on store

isbn

book ISBN number

title

book title

genre

comma separated book genre

publisher

name of book publisher

author

name of book author

copies

total number of book copies on store

borrowers - registered library members

id

member unique id

registered

date the member joined library

address

member address

name

full member name

phone_number

member phone number

program

membership program type (standard, premium or vip)

issues - borrowed books events

id

unique event id

borrower_id

id of the member that borrowed the book

isbn

is of the borrowed book

date

date of borrow event

returns - returned books events

id

event id equal to borrow issue id

date

date of return event

Managing the Cohort object

Description

The list of methods designed for managing the Cohort configuration and state.

• add_source - Add source to Cohort object.

• update_source - Update Cohort object source.

• add_step - Add step to Cohort object.

• rm_step - Remove step from Cohort object.

• add_filter - Add filter to Cohort step.

• rm_filter - Remove filter from Cohort step.

• update_filter - Update filter configuration.

• run - Run data filtering.

Value

The object of class 'Cohort' having the modified configuration dependent on the used method.

Managing the Source object

Description

The list of methods designed for managing the Source configuration and state.

• add_step - Add step to Source object.

• rm_step - Remove step from Source object.

• add_filter - Add filter to Source step.

• rm_filter - Remove filter from Source step.

• update_filter - Update filter configuration.

Value

The object of class 'Source' having the modified configuration dependent on the used method.

See Also

managing-cohort

Plot filter related Cohort data.

Description

For specified filter the method calls filter-related plot method to present data.

Usage

plot_data(x, step_id, filter_id, ..., state = "post")

Arguments

Value

Filter-specific plot.

See Also

cohort-methods

Define Source datasets primary keys

Description

Primary keys can be defined as 'primary_keys' parameter of set_source method. Currently, primary keys are used only to show keys information in attrition plot (See attrition).

Usage

primary_keys(...)

Arguments

Value

List of class 'primary_keys' storing data_keys objects.

Examples

primary_keys(
  data_key('books', 'book_id'),
  data_key('borrowed', c('user_id', 'books_id', 'date'))
)

Register a custom filter type

Description

Registers an S7 filter constructor so it can be used with filter("type", ...). The constructor must return an object inheriting from CbFilter.

Usage

register_filter_type(type, constructor)

Arguments

Examples

## Not run: 
MyCbFilter <- S7::new_class("MyCbFilter",
  parent = CbFilter,
  package = "mypackage",
  properties = list(dataset = S7::class_character, variable = S7::class_character),
  constructor = function(id = NULL, name = NULL, variable, dataset,
                         description = NULL, domain = NULL, ...) {
    id <- id %||% .default_filter_id(dataset, variable)
    name <- name %||% id
    S7::new_object(S7::S7_object(),
      type = "my_filter", id = id, name = name,
      dataset = dataset, variable = variable,
      active = TRUE, description = description, domain = domain,
      extra = list(...), private = list(input_param = "value")
    )
  }
)
register_filter_type("my_filter", MyCbFilter)
# Now filter("my_filter", ...) works

## End(Not run)

Restore Cohort object.

Description

The method allows to restore Cohort object with provided configuration state.

Usage

restore(
  x,
  state,
  modifier = function(prev_state, state) state,
  run_flow = FALSE
)

Arguments

Value

The 'Cohort' class object having the state restored based on provided config.

See Also

cohort-methods

Remove filter definition

Description

Remove filter definition

Usage

rm_filter(x, step_id, filter_id, ...)

## S3 method for class 'Cohort'
rm_filter(
  x,
  step_id,
  filter_id,
  run_flow = FALSE,
  hook = list(pre = get_hook("pre_rm_filter_hook"), post =
    get_hook("post_rm_filter_hook")),
  ...
)

## S3 method for class 'Source'
rm_filter(x, step_id, filter_id, ...)

Arguments

Value

Method dependent object (i.e. 'Cohort' or 'Source') having selected filter removed.

See Also

managing-cohort, managing-source

Remove filtering step definition

Description

Remove filtering step definition

Usage

rm_step(x, step_id, ...)

## S3 method for class 'Cohort'
rm_step(
  x,
  step_id,
  run_flow = FALSE,
  hook = list(pre = get_hook("pre_rm_step_hook"), post = get_hook("post_rm_step_hook")),
  ...
)

## S3 method for class 'Source'
rm_step(x, step_id, ...)

Arguments

Value

Method dependent object (i.e. 'Cohort' or 'Source') having selected step removed.

See Also

managing-cohort, managing-source

Trigger data calculations.

Description

Trigger data calculations.

Usage

run(x, min_step_id, step_id)

Arguments

Value

The object of class 'Cohort' having up-to-date data based on the Cohort state.

See Also

managing-cohort

Create Cohort source

Description

Source is an object storing information about data source such as source type, primary keys and relations between stored data.

Usage

set_source(
  dtconn,
  ...,
  primary_keys = NULL,
  binding_keys = NULL,
  source_code = NULL,
  description = NULL,
  available_filters = NULL,
  compute_meta_stats = getOption("cb.source_filters_meta_stats", TRUE)
)

## S3 method for class 'tblist'
set_source(
  dtconn,
  primary_keys = NULL,
  binding_keys = NULL,
  source_code = NULL,
  description = NULL,
  available_filters = NULL,
  compute_meta_stats = getOption("cb.source_filters_meta_stats", TRUE),
  ...
)

Arguments

Value

R6 object of class inherited from 'dtconn'.

Examples

mtcars_source <- set_source(
  tblist(mtcars = mtcars),
  source_code = quote({
    source <- list(dtconn = list(datasets = mtcars))
  })
)
mtcars_source$attributes

Describe the structure of a source

Description

'shape()' is an S3 generic that summarizes a source for programmatic or LLM-based inspection. Called with only a 'source', it returns a structured list 'list(datasets, filters)' where 'datasets' maps each dataset name to its description text and 'filters' is keyed by filter id (each entry describing the filter's 'dataset', 'type', 'description', 'variables', and 'domain').

Usage

shape(source, ...)

## Default S3 method:
shape(source, field, subfield, ...)

## S3 method for class 'tblist'
shape(source, field, subfield, domains = TRUE, ...)

Arguments

Details

Called with a 'field' (and optional 'subfield'), it instead performs a description-text lookup, returning the description stored for that dataset/variable. This form is used internally by the Cohort 'show_help()' method.

Value

Either a 'list(datasets, filters)' metadata structure or, when 'field' is supplied, the description text for the requested entry.

See Also

[describe()], [autofilter()]

Source compatibility methods.

Description

List of methods that allow compatibility of different source types. Most of the methods should be defined in order to make new source layer functioning. See 'Details' section for more information.

Usage

.init_step(source, ...)

## Default S3 method:
.init_step(source, ...)

.collect_data(source, data_object)

## Default S3 method:
.collect_data(source, data_object)

.get_stats(source, data_object)

## Default S3 method:
.get_stats(source, data_object)

.pre_filtering(source, data_object, step_id)

.post_filtering(source, data_object, step_id)

.post_binding(source, data_object, step_id)

.repro_code_tweak(source, code_data)

## Default S3 method:
.pre_filtering(source, data_object, step_id)

## Default S3 method:
.post_filtering(source, data_object, step_id)

## Default S3 method:
.post_binding(source, data_object, step_id)

.get_attrition_label(source, step_id, step_filters, ...)

## Default S3 method:
.get_attrition_label(source, step_id, step_filters, ...)

.get_attrition_count(source, data_stats, ...)

## Default S3 method:
.get_attrition_count(source, data_stats, ...)

.run_binding(source, ...)

## Default S3 method:
.run_binding(source, binding_key, data_object_pre, data_object_post, ...)

## S3 method for class 'tblist'
.init_step(source, ...)

## S3 method for class 'tblist'
.collect_data(source, data_object)

## S3 method for class 'tblist'
.get_stats(source, data_object)

Arguments

Details

The package is designed to make the functionality work with multiple data sources. Data source can be based for example on list of tables, connection to database schema or API service that allows to access and operate on data. In order to make new source type layer functioning, the following list of methods should be defined:

• .init_source - Defines how to extract data object from source. Each filtering step assumes to be operating on resulting data object (further named data_object) and returns object of the same type and structure.

• .collect_data - Defines how to collect data (into R memory) from 'data_object'.

• .get_stats - Defines what 'data_object' statistics should be calculated and how. When provided the stats can be extracted using stat.

• .pre_filtering - (optional) Defines what operation on 'data_object' should be performed before applying filtering in the step.

• .post_filtering - (optional) Defines what operation on 'data_object' should be performed after applying filtering in the step (before running binding).

• .post_binding - (optional) Defines what operation on 'data_object' should be performed after applying binding in the step.

• .run_binding - (optional) Defines how to handle post filtering data binding. See more about binding keys at binding-keys.

• .get_attrition_count and .get_attrition_label - Methods defining how to get statistics and labels for attrition plot.

• .repro_code_tweak - (optional) Default method passed as a 'modifier' argument of code function. Aims to modify reproducible code into the final format.

Except from the above methods, you may extend the existing or new source with providing custom filtering methods. See 'vignette("custom-filters")'. In order to see more details about how to implement custom source check 'vignette("custom-extensions")'.

Value

Depends on specific method. See 'vignette("custom-extensions")' for more details.

Get Cohort related statistics.

Description

Display data statistics related to specified step or filter.

Usage

stat(x, step_id, filter_id, ..., state = "post")

Arguments

Value

List of filter-specific values summing up underlying filter data.

See Also

cohort-methods

Create filtering step

Description

Steps all to perform multiple stages of Source data filtering.

Usage

step(...)

Arguments

Value

List of class 'cb_step' storing filters configuration.

Examples

iris_step_1 <- step(
  filter('discrete', dataset = 'iris', variable = 'Species', value = 'setosa'),
  filter('discrete', dataset = 'iris', variable = 'Petal.Length', range = c(1.5, 2))
)
iris_step_2 <- step(
  filter('discrete', dataset = 'iris', variable = 'Sepal.Length', range = c(5, 10))
)

# Add step directly to Cohort
iris_source <- set_source(tblist(iris = iris))
coh <- iris_source |>
  cohort(
    iris_step_1,
    iris_step_2
  ) |>
  run()

nrow(get_data(coh, step_id = 1)$iris)
nrow(get_data(coh, step_id = 2)$iris)

# Add step to Cohort using add_step method
coh <- iris_source |>
  cohort()
coh <- coh |>
  add_step(iris_step_1) |>
  add_step(iris_step_2) |>
  run()

Sum up Cohort state.

Description

Sum up Cohort state.

Usage

sum_up(x, to_string = FALSE)

Arguments

Value

When 'to_string = FALSE' (default), 'invisible(NULL)' (prints to console). When 'to_string = TRUE', a single character string.

See Also

cohort-methods

Create in memory tables connection

Description

Create data connection as a list of loaded data frames. The object should be used as 'dtconn' argument of set_source.

Usage

tblist(..., names, .class = NULL)

as.tblist(x, ..., .class = NULL)

Arguments

Value

Object of class 'tblist' being a named list of data frames.

Examples

str(tblist(mtcars))
str(tblist(mtcars, iris))
str(tblist(MT = mtcars, IR = iris))
str(tblist(mtcars, iris, names = c("MT", "IR")))

S7 class wrapper for the 'tblist' source

Description

S7 representation of the built-in 'tblist' source class, used as the source side of S7 dual dispatch when registering filter methods (e.g. 'S7::method(cb_filter_data, list(CbFilterDiscrete, tblist_class))'). See 'vignette("custom-filters")'.

Usage

tblist_class

Format

An S7 S3-class wrapper created with [S7::new_S3_class()].

Update filter definition

Description

Update filter definition

Usage

update_filter(x, step_id, filter_id, ...)

## S3 method for class 'Cohort'
update_filter(x, step_id, filter_id, ..., run_flow = FALSE)

## S3 method for class 'Source'
update_filter(x, step_id, filter_id, ...)

Arguments

Value

Method dependent object (i.e. 'Cohort' or 'Source') having selected filter updated.

See Also

managing-cohort, managing-source

Update source in Cohort object.

Description

Update source in Cohort object.

Usage

update_source(x, source, keep_steps = !has_steps(source), run_flow = FALSE)

Arguments

Value

The 'Cohort' class object with updated 'Source' definition.

See Also

managing-cohort