Package {rMosaic}

Type: Package
Title: R Bindings to the 'Mosaic' Visualization Framework
Version: 0.2.0
Description: Provides R bindings for 'Mosaic', a declarative grammar for linked, data-driven visualizations backed by 'DuckDB'. The package supplies 'htmlwidgets' and 'shiny' helpers for rendering 'Mosaic' specifications from R, including optional browser-side 'DuckDB-WASM' execution and selection export helpers for exploratory workflows.
License: MIT + file LICENSE
URL: https://github.com/TiRizvanov/rMosaic
BugReports: https://github.com/TiRizvanov/rMosaic/issues
Encoding: UTF-8
Language: en-US
RoxygenNote: 7.3.3
Depends: R (≥ 4.1.0)
Imports: htmlwidgets (≥ 1.5.4), htmltools (≥ 0.5.0), shiny (≥ 1.7.0), jsonlite (≥ 1.8.0), yaml (≥ 2.3.0), DBI (≥ 1.1.0), duckdb (≥ 1.4.0), stats
Suggests: arrow (≥ 12.0.0), knitr, rmarkdown, rstudioapi, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-09-19 19:57:51 UTC; timurrizvanov
Author: Timur Rizvanov [aut, cre], Edward C. Ruiz [aut], Ruben Dries [aut, rev], Dries Lab [fnd] (Host laboratory and funding source), Boston University [fnd] (Undergraduate Research Opportunities Program (UROP))
Maintainer: Timur Rizvanov <timurr@bu.edu>
Repository: CRAN
Date/Publication: 2026-09-20 02:30:24 UTC

rMosaic: R Bindings to the 'Mosaic' Visualization Framework

Description

Provides R bindings for 'Mosaic', a declarative grammar for linked, data-driven visualizations backed by 'DuckDB'. The package supplies 'htmlwidgets' and 'shiny' helpers for rendering 'Mosaic' specifications from R, including optional browser-side 'DuckDB-WASM' execution and selection export helpers for exploratory workflows.

Acknowledgements

Developed in the Dries Lab at Boston University. This work was supported by the Dries Lab and the Boston University Undergraduate Research Opportunities Program (UROP).

Author(s)

Maintainer: Timur Rizvanov timurr@bu.edu

Authors:

Other contributors:

See Also

Useful links:

Retrieve a stored Mosaic selection

Description

After pressing "Import Selection" in a runMosaicWithExport app, the selected data are stored inside the package under the name printed in the status bar (e.g. "mosaic_sel_1"). Use this function to retrieve a selection by that name.

Usage

get_mosaic_selection(name)

Arguments

name

Character scalar: the variable name returned by the import button (e.g. "mosaic_sel_1").

Value

The stored data.frame, or NULL with a warning if the name is not found.

See Also

list_mosaic_selections

List all stored Mosaic selections

Description

Returns the names of all selections currently held in the package store.

Usage

list_mosaic_selections()

Value

Character vector of selection names.

See Also

get_mosaic_selection

Render a Mosaic visualization in Shiny

Description

Renders a Mosaic visualization using the provided specification and data.

Usage

mosaic(
  spec,
  specType = c("auto", "json", "yaml", "esm"),
  data = NULL,
  backend = c("r", "wasm"),
  data_transport = c("auto", "file", "inline"),
  data_dir = NULL,
  width = NULL,
  height = NULL,
  con = NULL
)

Arguments

spec

JSON/YAML (as R list, text, or file) or ESM JS code (text or file).

specType

One of "auto" (default), "json", "yaml", or "esm".

data

Named list of input tables. Each element is a data.frame to register in DuckDB or, when 'con' is supplied, a single SQL string evaluated on 'con': with 'backend = "r"' it is exposed as a temporary view named after the element; with 'backend = "wasm"' its result is streamed from DuckDB into the browser payload without materialising the rows in R. Optional for 'backend = "r"' when 'con' already holds the tables the spec refers to.

backend

Database backend: "r" (default) for R DuckDB or "wasm" for browser WASM DuckDB.

data_transport

How 'backend = "wasm"' input tables are delivered to the browser. '"auto"' uses '"file"' when 'data_dir' is supplied and otherwise falls back to '"inline"' for portable widgets; '"inline"' keeps the row-JSON path; '"file"' writes Arrow IPC files to 'data_dir' and registers them in DuckDB-WASM by URL. SQL-string elements of 'data' are exported as Arrow IPC streams when DuckDB can write them (the community 'nanoarrow' extension, else record-batch streaming through the 'arrow' package) and otherwise as Parquet files; the widget payload records the method used per table under 'input_exports'. Set 'options(rMosaic.export_methods = ...)' to a subset of 'c("copy_arrows", "record_batch", "copy_parquet")' to restrict the ladder. The 'nanoarrow' extension is only loaded, never installed: on a connection where it is absent the 'copy_arrows' rung is skipped.

data_dir

Directory for '"file"' transport; when omitted a session temporary directory is used. The exported files travel with the widget as an html dependency attachment, so the RStudio Viewer, Shiny and 'htmlwidgets::saveWidget(selfcontained = FALSE)' all resolve them ('selfcontained = TRUE' is not supported for file transport).

width

CSS or pixel width (e.g. "100%", "600px", or numeric).

height

CSS or pixel height.

con

Optional 'DBI::DBIConnection' to a DuckDB database. With 'backend = "r"' the widget queries this connection in place instead of copying data into a fresh in-memory DuckDB, so tables that already live in the database are never loaded into R; data.frames in 'data' are still written to it with 'overwrite = TRUE', replacing an existing table of the same name. In a Shiny session the widget's query channel executes the SQL the page sends, including 'exec' statements, on this connection, so supply a connection whose contents may change. rMosaic never disconnects a supplied connection; only the connections it opens itself are closed when the Shiny session ends. With 'backend = "wasm"' the connection is used solely to export the SQL-string elements of 'data'.

Value

An htmlwidget that renders the Mosaic visualization.

Shiny output for Mosaic widget

Description

Use this in the UI to create a placeholder for the Mosaic visualization.

Usage

mosaicOutput(outputId, width = "100%", height = "400px")

Arguments

outputId

output variable name

width, height

CSS dimensions (e.g. '100%', '400px') for the container.

Value

A Shiny UI output element for a Mosaic htmlwidget.

Shiny render function for Mosaic

Description

Use this in the server to render the Mosaic visualization to the output.

Usage

renderMosaic(expr, env = parent.frame(), quoted = FALSE)

Arguments

expr

An expression that generates a call to mosaic().

env

The environment in which to evaluate expr.

quoted

Is expr a quoted expression (with quote())? This is useful if you want to save an expression in a variable.

Value

A Shiny render function for use in a server output assignment.

Run a Mosaic Shiny App in the RStudio Viewer

Description

Launches a Shiny application displaying the Mosaic visualization.

Usage

runMosaicApp(
  spec,
  specType = c("auto", "json", "yaml", "esm"),
  data,
  backend = c("r", "wasm"),
  title = NULL,
  width = "100%",
  height = "600px",
  con = NULL
)

Arguments

spec

JSON/YAML (as R list, text, or file) or ESM JS code (text or file).

specType

One of "auto" (default), "json", "yaml", or "esm".

data

Named list of input tables. Each element is a data.frame to register in DuckDB or, when 'con' is supplied, a single SQL string evaluated on 'con': with 'backend = "r"' it is exposed as a temporary view named after the element; with 'backend = "wasm"' its result is streamed from DuckDB into the browser payload without materialising the rows in R. Optional for 'backend = "r"' when 'con' already holds the tables the spec refers to.

backend

Database backend: "r" (default) for R DuckDB or "wasm" for browser WASM DuckDB.

title

Optional page title

width

CSS or pixel width (e.g. "100%", "600px", or numeric).

height

CSS or pixel height.

con

Optional 'DBI::DBIConnection' to a DuckDB database. With 'backend = "r"' the widget queries this connection in place instead of copying data into a fresh in-memory DuckDB, so tables that already live in the database are never loaded into R; data.frames in 'data' are still written to it with 'overwrite = TRUE', replacing an existing table of the same name. In a Shiny session the widget's query channel executes the SQL the page sends, including 'exec' statements, on this connection, so supply a connection whose contents may change. rMosaic never disconnects a supplied connection; only the connections it opens itself are closed when the Shiny session ends. With 'backend = "wasm"' the connection is used solely to export the SQL-string elements of 'data'.

Value

A Shiny application object.

Run a Mosaic app and export brush/query selections back to R

Description

Runs a Mosaic app and allows exporting selections to R.

Usage

runMosaicExport(
  spec,
  specType = "auto",
  data,
  title = NULL,
  width = "100%",
  height = "600px",
  selection_env = NULL,
  con = NULL
)

Arguments

spec

JSON/YAML (as R list, text, or file) or ESM JS code (text or file).

specType

One of "auto" (default), "json", "yaml", or "esm".

data

Named list of input tables. Each element is a data.frame to register in DuckDB or, when 'con' is supplied, a single SQL string evaluated on 'con': with 'backend = "r"' it is exposed as a temporary view named after the element; with 'backend = "wasm"' its result is streamed from DuckDB into the browser payload without materialising the rows in R. Optional for 'backend = "r"' when 'con' already holds the tables the spec refers to.

title

Optional page title

width

CSS or pixel width (e.g. "100%", "600px", or numeric).

height

CSS or pixel height.

selection_env

where to store extracted selections

con

Optional 'DBI::DBIConnection' to a DuckDB database. With 'backend = "r"' the widget queries this connection in place instead of copying data into a fresh in-memory DuckDB, so tables that already live in the database are never loaded into R; data.frames in 'data' are still written to it with 'overwrite = TRUE', replacing an existing table of the same name. In a Shiny session the widget's query channel executes the SQL the page sends, including 'exec' statements, on this connection, so supply a connection whose contents may change. rMosaic never disconnects a supplied connection; only the connections it opens itself are closed when the Shiny session ends. With 'backend = "wasm"' the connection is used solely to export the SQL-string elements of 'data'.

Value

A Shiny application object. When the user imports a selection, the selected rows are assigned into selection_env as mosaic_sel_<n>.

Run a Mosaic Shiny App with selection export

Description

Launches a Shiny application that allows selecting data points and exporting them to an R environment.

Usage

runMosaicWithExport(
  spec,
  specType = c("auto", "json", "yaml", "esm"),
  data,
  title = NULL,
  width = "100%",
  height = "600px",
  selection_env = NULL,
  con = NULL
)

Arguments

spec

JSON/YAML (as R list, text, or file) or ESM JS code (text or file).

specType

One of "auto" (default), "json", "yaml", or "esm".

data

Named list of input tables. Each element is a data.frame to register in DuckDB or, when 'con' is supplied, a single SQL string evaluated on 'con': with 'backend = "r"' it is exposed as a temporary view named after the element; with 'backend = "wasm"' its result is streamed from DuckDB into the browser payload without materialising the rows in R. Optional for 'backend = "r"' when 'con' already holds the tables the spec refers to.

title

Optional page title

width

CSS or pixel width (e.g. "100%", "600px", or numeric).

height

CSS or pixel height.

selection_env

Environment to store selections in

con

Optional 'DBI::DBIConnection' to a DuckDB database. With 'backend = "r"' the widget queries this connection in place instead of copying data into a fresh in-memory DuckDB, so tables that already live in the database are never loaded into R; data.frames in 'data' are still written to it with 'overwrite = TRUE', replacing an existing table of the same name. In a Shiny session the widget's query channel executes the SQL the page sends, including 'exec' statements, on this connection, so supply a connection whose contents may change. rMosaic never disconnects a supplied connection; only the connections it opens itself are closed when the Shiny session ends. With 'backend = "wasm"' the connection is used solely to export the SQL-string elements of 'data'.

Value

A Shiny application object. When the user imports a selection, the selected rows are assigned into selection_env as mosaic_sel_<n>.