Package 'blockr.dm'

Title: Relational Data Management Blocks for 'blockr'
Description: Blocks for working with relational data in 'blockr.core' boards, built on the 'dm' package. Combine data frames into a data model, set primary and foreign keys, select, pull and flatten tables, and filter across linked tables with cascading through foreign keys. A crossfilter block shows linked counts for any column of any table and filters them in the browser.
Authors: Christoph Sax [aut, cre], Square, Inc. [cph] (crossfilter2 JavaScript library), Mike Bostock [cph] (crossfilter2 JavaScript library), crossfilter contributors [cph] (crossfilter2 JavaScript library), The Dart project authors [cph] (quicksort implementation in crossfilter2)
Maintainer: Christoph Sax <[email protected]>
License: GPL (>= 3)
Version: 0.0.104
Built: 2026-11-19 08:16:06 UTC
Source: https://github.com/BristolMyersSquibb/blockr.dm

Help Index


Custom output for dm blocks

Description

Displays dm structure as an interactive diagram showing tables and relationships.

Usage

## S3 method for class 'dm_add_keys_block'
block_output(x, result, session)

## S3 method for class 'dm_block'
block_output(x, result, session)

Arguments

x

The block object

result

The dm result

session

Shiny session


Custom render trigger for dm blocks

Description

Override transform_block's render trigger which tries to access board options that may not be set. dm blocks don't need pagination.

Usage

## S3 method for class 'dm_block'
block_render_trigger(x, session = blockr.core::get_session())

Arguments

x

The block object

session

Shiny session


Custom UI for dm blocks

Description

Custom UI for dm blocks

Usage

## S3 method for class 'dm_add_keys_block'
block_ui(id, x, ...)

## S3 method for class 'dm_block'
block_ui(id, x, ...)

Arguments

id

Namespace ID

x

The block object

...

Additional arguments


Level order of a grouping column

Description

The order a column's levels take wherever they are listed: in the crossfilter's group definition, in the stamped Group column and in the tables built on it. A factor gives the levels that occur, in levels() order. Anything else gives its distinct non-missing values, sorted.

Usage

crossfilter_level_order(x)

Arguments

x

A vector.

Value

A character vector of levels.

Examples

crossfilter_level_order(factor(c("b", "a"), levels = c("c", "b", "a")))
crossfilter_level_order(c("b", NA, "a", "b"))

Filter trail

Description

The record of which filters produced a table, carried on the data itself as a blockr_filters attribute so that any downstream consumer (a chart caption, a table footnote, a download) can print what was applied without knowing anything about the board.

trail_key(), trail_expr() and provenance() are deprecated and will stop being exported. They stay for blocks written against blockr.dm 0.0.95 and log a warning the first time each is called in a session. A block passes its module namespace (session$ns("")) as the key to add_filter_trail(), wraps its expression in that call itself, and reads the blockr_provenance attribute of a table.

Usage

filter_trail(x, tables = NULL)

add_filter_trail(x, key, clause, tables = NULL)

trail_key(session = shiny::getDefaultReactiveDomain())

trail_expr(
  inner,
  key = NULL,
  clause = NULL,
  data = quote(data),
  table = NULL,
  tables = NULL,
  count = FALSE
)

provenance(x)

Arguments

x

A data frame or a dm.

tables

For a dm: the tables to write the clause on (add_filter_trail()) or read the trail from (filter_trail()). NULL, the default, means every table. Ignored for a data frame.

key

Name the clause is stored under, unique to the block that writes it.

clause

What the block filtered, e.g. "segment = Consumer; city = Boston". An empty or missing clause adds nothing, so a filter with nothing selected leaves no trace.

session

The block server's Shiny session.

inner

The expression the block would otherwise return.

data, count

Accepted and ignored: the trail upstream rides through on the tables, and the trail no longer counts subjects.

table

The one table a filter narrowed without cascading. Same as tables with one name.

Details

The trail is a named character vector, keyed by block. A filter block writes its clause under its own key, so two branches meeting at a fan-in collapse to one entry per block, and a consumer can map a clause back to the block that set it.

Value

filter_trail() returns a named character vector, or NULL when nothing is recorded. On a dm it is the union of the tables' trails in the order the clauses were added. add_filter_trail() returns x with the clause added. The deprecated trail_key() returns a string, trail_expr() a call, and provenance() a list or NULL.

Where it lives

On a data frame the attribute sits on the frame. On a dm it sits on the tables, not on the dm object: every dm verb (dm::dm_filter(), zooming, key edits) rebuilds the dm and drops attributes set on it, but keeps the attributes of its tables, and dm::pull_tbl() and dm::dm_flatten_to_tbl() hand a table's attributes on to the frame they return (a flatten keeps the start table's). So a trail written onto the tables reaches every frame cut from the dm with no further code, the way dplyr keeps a data frame's attributes through filter(), mutate() and joins.

Which tables a clause goes on says which tables the filter narrowed. dm::dm_filter() cascades over the keys, so a filter written against orders narrows customers and through it every other table: by default the clause goes on every table. A filter that narrows one table without cascading passes that table as tables, and a frame pulled from another table does not carry the clause.

dplyr::summarise() and tidyr::pivot_wider() do not keep attributes, so a block that aggregates has to copy the trail across itself.

Examples

d <- data.frame(x = 1:3)
d <- add_filter_trail(d, "segment", "segment = Consumer")
filter_trail(d)

Crossfilter Block

Description

Client-side crossfilter using crossfilter2.js. R builds lookup tables and ships them to the browser; all filtering, counting, and UI updates happen in JavaScript for instant responsiveness. Accepts either a data frame or a dm object.

Usage

new_crossfilter_block(
  active_dims = list(),
  filters = list(),
  range_filters = list(),
  measure = NULL,
  agg_func = NULL,
  featured = character(),
  pinned = NULL,
  groups = list(),
  subgroup = NULL,
  group_none = FALSE,
  ...
)

Arguments

active_dims

Named list of per-table active filter columns. E.g., list(customers = c("segment", "city"), categories = c("category_name"))

filters

Named list of per-table categorical filters. E.g., list(customers = list(segment = c("Consumer")))

range_filters

Named list of per-table range filters. E.g., list(products = list(unit_price = c(10, 100)))

measure

Measure column as "table.column" string, or NULL for row counts. E.g., "orders.amount".

agg_func

Aggregation function: "sum" or "mean". Only used when measure is set.

featured

Columns worth showing up front: they get a pill each above the cards, rank first in the search, and are the columns pinned may name. A pill's one job is to open and close that column's filter card. E.g. c("segment", "city", "category_name"). Empty (the default) means no pills, but the row is still there: it carries ⁠+ More filters⁠, which opens the column search and is the only way in once blockr.dock has hidden the gear on a simplified or locked board. The vocabulary itself is edited in the gear, as a ⁠Shown up front⁠ field beside Measure and Aggregation: dropping a column from it also takes it out of ⁠Group by⁠, for every reader of the board, which is a setting and not a filter.

pinned

The single column the block reports as the board's group, chosen in the ⁠Group by⁠ select at the top of the block. Only featured columns on the parent table qualify. Grouping is independent of filtering: a pinned column need not have a card, and a card does not make a column the group. NULL (the default) means no group.

groups

Group definitions for the pinned column and the subgroup, edited under the ⁠Group by⁠ and ⁠Subgroup by⁠ selects: Columns picks the levels and pools shown, in order, and each pool is a field of its own. A named list keyed by column, so switching the group column and back, or swapping group and subgroup, keeps each definition. An entry is list(columns = list(list(name = , members = , custom = ), ...)), the columns in table order. A column with an empty name is one level shown on its own; a named one is a pool of its members, custom = FALSE meaning the name follows the members. A level may be in two columns (shown on its own and pooled). A level in no column is not shown. A pool that is defined but not shown sits in hidden_pools, same shape as columns plus at, its place in the list, so that it is kept without being a column. A column with no entry shows every level in crossfilter_level_order(), one column each. The older shape, ⁠list(show = <levels>, pools = <list>)⁠, is still read: its levels come first, then its pools. The block only records the definition; a package building on it (blockr.pharma's population filter, for one) applies it.

subgroup

A second column the board is split by, under pinned, chosen in the ⁠Subgroup by⁠ select below the groups. Same eligible columns as pinned, minus the pinned one. NULL (the default) means no subgroup. Its levels are pooled like the group's, through its entry in groups, and a button in its field swaps it with pinned. Like pinned, the block only records it; a package building on it, such as blockr.pharma's population filter, decides what to do with it.

group_none

Whether the ⁠Group by⁠ select offers "(none)", which unpins the group. Off by default, set in the gear (⁠Group by offers (none)⁠). The block only records the choice; a package building on it decides what an ungrouped board means (blockr.pharma's population filter stamps its group column as NA in every row).

...

Forwarded to blockr.core::new_transform_block(). A package building on this block passes its own class here: the subclass has to be set at construction, which is where block metadata is resolved from the registry. It is not a formal because every constructor formal has to come back out as block state. The same holds for subject_unit: the word the header counts the subject table's keys in (for example "customers"), set by a package that knows what its subjects are. Unset, the header counts rows.

Value

A blockr transform block with client-side crossfiltering


dm Add Keys Block Constructor

Description

This block adds primary and foreign key relationships to a dm object. It allows selecting a table and column to set as primary key, and optionally link it as a foreign key from one or more other tables.

Usage

new_dm_add_keys_block(
  pk_table = "",
  pk_column = "",
  fk_tables = character(0),
  fk_column = "",
  ...
)

Arguments

pk_table

Character, the table to add primary key to. Default "".

pk_column

Character, the column to use as primary key. Default "".

fk_tables

Character vector, tables containing the foreign key. Default character(0).

fk_column

Character, the column to use as foreign key. Default "".

...

Forwarded to blockr.core::new_transform_block()

Details

Primary keys uniquely identify rows in a table. Foreign keys reference the primary key of another table, establishing relationships.

In a customer and orders model, customer_id is typically the primary key in customers and a foreign key in orders.

Value

A block object for adding keys to dm objects

Examples

# Add customer_id as key linking customers to orders
new_dm_add_keys_block(
  pk_table = "customers",
  pk_column = "customer_id",
  fk_tables = "orders",
  fk_column = "customer_id"
)

Create dm Block Constructor

Description

This block combines multiple data frames and/or dm objects into a single dm (data model) object.

Usage

new_dm_block(infer_keys = TRUE, ...)

Arguments

infer_keys

Logical, whether to automatically infer primary and foreign key relationships from columns with matching names. Default is TRUE.

...

Forwarded to blockr.core::new_transform_block()

Details

Inputs can be data frames or existing dm objects:

  • Data frames are added as new tables in the dm

  • Existing dm objects have their tables merged into the result

  • If table names conflict, later inputs overwrite earlier ones

Value

A block object for creating dm objects

Examples

# Create a dm block
new_dm_block()

# Create a dm block with auto-inferred relationships
new_dm_block(infer_keys = TRUE)

if (interactive()) {
  library(blockr.core)
  library(blockr.dm)

  # Combine multiple tables into a dm
  serve(
    new_board(
      blocks = list(
        airlines = new_dataset_block(
          dataset = "airlines", package = "nycflights13"
        ),
        flights = new_dataset_block(
          dataset = "flights", package = "nycflights13"
        ),
        dm_obj = new_dm_block()
      ),
      links = c(
        new_link("airlines", "dm_obj", "1"),
        new_link("flights", "dm_obj", "2")
      )
    )
  )
}

DM Example Block

Description

A data block that provides ready-to-use dm objects from a built-in catalog of example datasets. The dropdown shows only datasets whose required packages are installed. A built-in BI star schema is always available.

Usage

new_dm_example_block(dataset = "bi_star_schema", ...)

Arguments

dataset

Character, the ID of the dm example to load. Defaults to "bi_star_schema" (always available). See dm_example_choices().

...

Forwarded to blockr.core::new_data_block()

Details

To add a new dataset, add an expression builder function (e.g., my_data_expr()) and wire it into dm_example_choices() and dm_example_expr().

Value

A data block of class c("dm_example_block", "dm_block").

Examples

if (interactive()) {
  library(blockr.core)
  library(blockr.dm)
  serve(new_dm_example_block())
}

dm Filter Block Constructor

Description

Filters a dm object by applying one or more conditions to a selected table. The filter cascades to related tables via semi-joins on foreign key relationships (handled by dm::dm_filter()), keeping only rows that match across the data model.

Usage

new_dm_filter_block(
  table = "",
  state = list(conditions = list(), operator = "&"),
  ...
)

Arguments

table

Name of the dm table to filter. Default "" (none selected until data arrives).

state

Filter state as used by blockr.dplyr's filter block — a list with conditions (list of condition objects) and operator ("&" or "|").

...

Forwarded to blockr.core::new_transform_block().

Details

The condition UI is reused from blockr.dplyr's filter block: each condition is type-aware (categorical multi-select, numeric operator + value, or free R expression) and conditions are combined with & or |. A single table picker above the conditions selects which table in the dm the conditions apply to. Changing the table clears existing conditions.

Value

A block object for filtering dm objects.

Examples

# Keep the customers in the "Consumer" segment, and the orders that follow
new_dm_filter_block(
  table = "customers",
  state = list(
    conditions = list(list(
      type = "values", column = "segment",
      values = list("Consumer"), mode = "include"
    )),
    operator = "&"
  )
)

dm Flatten Block Constructor

Description

This block flattens a dm object into a single data frame by joining all related tables based on their foreign key relationships.

Usage

new_dm_flatten_block(
  start_table = "",
  include_tables = character(),
  join_type = "left",
  recursive = TRUE,
  ...
)

Arguments

start_table

Character, the table to start flattening from. Default "".

include_tables

Character vector, specific tables to include in the join. If empty, all reachable tables are included.

join_type

Character, type of join to use: "left", "inner", "full", "right". Default "left".

recursive

Logical, whether to recursively join all related tables. Default TRUE.

...

Forwarded to blockr.core::new_transform_block()

Details

The starting table determines the base of the join. Related tables are joined based on their foreign key relationships. With recursive = TRUE, all transitively related tables are included.

Use include_tables to limit which tables are joined - useful when you want to flatten only specific relationships (e.g., join orders with customers but not products).

Value

A block object for flattening dm objects

Examples

new_dm_flatten_block(start_table = "flights", recursive = TRUE)

new_dm_flatten_block(
  start_table = "orders",
  include_tables = c("customers"),
  join_type = "inner"
)

dm Pull Block Constructor

Description

This block extracts a single table from a dm object as a regular data frame. Use this after filtering to get a specific table for further analysis or visualization.

Usage

new_dm_pull_block(table = "", ...)

Arguments

table

Character, the name of the table to extract. Default "".

...

Forwarded to blockr.core::new_transform_block()

Value

A block object for extracting tables from dm objects

External control

table is externally controllable (see blockr.core::external_ctrl_vars()): a board update or an assistant can switch the pulled table with a mod delta, and the picker follows.

Examples

new_dm_pull_block(table = "flights")

Select tables from a dm object

Description

A block for selecting a subset of tables from a dm (data model) object. Uses dm::dm_select_tbl() to keep only the specified tables.

Usage

new_dm_select_block(tables = character(), ...)

Arguments

tables

Character vector. Names of tables to keep. If empty, all tables are kept (no filtering).

...

Forwarded to blockr.core::new_transform_block()

Value

A blockr transform block that filters tables from a dm object

External control

tables is externally controllable (see blockr.core::external_ctrl_vars()): a board update or an assistant can change the kept set with a mod delta, and the picker follows.

Examples

if (interactive()) {
  library(blockr.core)
  library(blockr.dm)
  serve(new_dm_select_block())
}

Drill filter block

Description

The destination for cross-block drill claims: a new_value_filter_block() that senders can find without being told, and that resolves a claimed column to a table in its own dm.

Usage

new_drill_filter_block(state = list(columns = list()), ...)

Arguments

state

List with columns — a list of column-object entries — and operator ("&" or "|", default "&") controlling how the per-column conditions combine on a data-frame input (same AND/OR pill as the blockr.dplyr filter block; a builder option, so it sits in the gear popover and shows once two or more fields are active). On a dm input the operator is ignored: the restriction cascades per-table through dm::dm_filter(), whose chaining is inherently AND, so the pill is not offered there. Each column entry has name (column name), table (source table; only when input is a dm), mode ("single" or "multi"), and values (character vector of selected values). Logical columns in single mode render as compact include-style checkbox rows: checked requires col %in% TRUE, unchecked means no constraint from that column (NOT a FALSE filter). To target FALSE/NA explicitly, flip the column to Multi (values plus the ⁠<NA>⁠ token) or use the blockr.dplyr filter block. (Legacy saved states with a logical single-select value of "FALSE" still evaluate as !(col %in% TRUE).) Old-style state (list(columns=character, modes=list, values=list)) is migrated to the current shape.

...

Additional arguments forwarded to blockr.core::new_transform_block().

Details

Put one on a board together with blockr.viz::new_ctrl_bridge_extension(). The two go together: the bridge opens the control channel and this block is what the channel writes into, so a board with a bridge and no drill filter has senders with nowhere to send, and a drill filter without a bridge is just a value filter.

Value

A block object.

One per board

A sender resolves its target by class and takes it only when there is exactly one candidate, so a second drill filter turns the drill back off rather than picking a winner. Use plain value filter blocks for every other filtering job on the board; they are not candidates and do not interfere.

What it does with a claim

A claim is a list of list(name=, mode=, values=) entries pushed into the block's state over the control channel. On a dm input each entry needs a table as well, and this block fills it in:

  • exactly one table carries the column: that table.

  • several carry it (an id such as customer_id is in several tables): the table where it is the PRIMARY KEY, because dm::dm_filter() cascades along foreign keys, so restricting the parent restricts the children too.

  • no table carries it: nothing is filtered and the block says which column it could not place. This means the sender claimed a column it DERIVED, and the fix belongs at the sender.

An entry that already names a valid table is left alone, so a sender that does set ctrl_table keeps working unchanged.

On a plain data frame input there are no tables to resolve and this block behaves exactly like a value filter.

Examples

if (interactive()) {
  library(blockr.core)
  library(blockr.dm)
  serve(
    new_drill_filter_block(),
    data = list(data = datasets::iris)
  )
}

Value filter block

Description

Minimal value filter for data frames or dm objects. The columns to filter on are chosen behind the gear icon (top-right of the block). Each column can be toggled between single-select (always constrains — auto-picks first value) and multi-select (empty selection passes through).

Usage

new_value_filter_block(state = list(columns = list()), ...)

Arguments

state

List with columns — a list of column-object entries — and operator ("&" or "|", default "&") controlling how the per-column conditions combine on a data-frame input (same AND/OR pill as the blockr.dplyr filter block; a builder option, so it sits in the gear popover and shows once two or more fields are active). On a dm input the operator is ignored: the restriction cascades per-table through dm::dm_filter(), whose chaining is inherently AND, so the pill is not offered there. Each column entry has name (column name), table (source table; only when input is a dm), mode ("single" or "multi"), and values (character vector of selected values). Logical columns in single mode render as compact include-style checkbox rows: checked requires col %in% TRUE, unchecked means no constraint from that column (NOT a FALSE filter). To target FALSE/NA explicitly, flip the column to Multi (values plus the ⁠<NA>⁠ token) or use the blockr.dplyr filter block. (Legacy saved states with a logical single-select value of "FALSE" still evaluate as !(col %in% TRUE).) Old-style state (list(columns=character, modes=list, values=list)) is migrated to the current shape.

...

Additional arguments forwarded to blockr.core::new_transform_block().

Details

When the upstream input is a dm, the gear popover gains a table selector so columns can be picked from any of the dm's tables. The emitted filter goes through dm::dm_filter(), so the restriction cascades through foreign keys to related tables.

Gear/popover UX, select widget, and click-through pill styling are reused from blockr.dplyr to match the look-and-feel of the crossfilter and dplyr transform blocks.

This is the value-selection member of the relational filter family, alongside new_dm_filter_block() (expression-style) and new_crossfilter_block(). It lives in blockr.dm because its dm path depends on dm; it is fully usable in a dashboard by composing it onto a board.

Examples

if (interactive()) {
  library(blockr.core)
  library(blockr.dm)
  serve(
    new_value_filter_block(
      state = list(
        columns = list(
          list(name = "Species", mode = "single", values = "setosa")
        )
      )
    ),
    data = list(data = iris)
  )
}

Register dm Blocks

Description

Registers the dm blocks with blockr.

Usage

register_dm_blocks()