Package {myIO}

myIO: Interactive Data Visualizations Using d3.js

Description

Create interactive 'd3.js' visualizations from R with built-in statistical transforms. Computes confidence intervals, regression fits, LOESS smoothing, moving averages, error bars, and uncertainty visualizations (quantile dot plots and fan charts) in R and renders them as composable chart layers via 'htmlwidgets'. Supports 36 chart types including boxplots, violin plots, Q-Q diagnostic plots, calendar heatmaps, survival curves, and group comparisons with pairwise significance testing. Also provides a machine-readable chart specification schema with validators so that large language model agents can author and verify charts. Works in 'RStudio', 'Shiny', and 'R Markdown'.

Author(s)

Maintainer: Ryan Morton morton@myma.us [copyright holder]

Other contributors:

• Mike Bostock (D3.js, d3-hexbin, and d3-sankey libraries) [copyright holder]

• James Hall (jsPDF library) [copyright holder]

• yWorks GmbH (jsPDF library) [copyright holder]

See Also

Useful links:

• https://mortonanalytics.github.io/myIO/

• https://github.com/mortonanalytics/myIO

• Report bugs at https://github.com/mortonanalytics/myIO/issues

Add a Layer to a myIO Chart

Description

Adds individual layer to a myIO widget

Usage

addIoLayer(
  myIO,
  type,
  color = NULL,
  label,
  data = NULL,
  mapping,
  transform = "identity",
  options = list(barSize = "large", toolTipOptions = list(suppressY = FALSE))
)

Arguments

Value

A modified myIO htmlwidget object with the new layer appended to the configuration.

Examples

myIO(data = mtcars) |>
  addIoLayer(
    type = "point", label = "points",
    mapping = list(x_var = "wt", y_var = "mpg")
  )

Remove DuckDB-WASM cache entries

Description

Remove DuckDB-WASM cache entries

Usage

clear_duckdb_wasm_cache(version = NULL)

Arguments

Value

Number of removed entries, invisibly.

Examples

## Not run: 
# Removes cached DuckDB-WASM binaries from the user cache.
clear_duckdb_wasm_cache()

## End(Not run)

Define Categorical Axis

Description

Function to define the x variable as categorical

Usage

defineCategoricalAxis(myIO, xAxis = TRUE, yAxis = FALSE)

Arguments

Value

A modified myIO htmlwidget object with categorical axis configured.

Examples

# Define x axis as categorical
myIO() |> defineCategoricalAxis(xAxis = TRUE)

# Define both axes as categorical
myIO() |> defineCategoricalAxis(xAxis = TRUE, yAxis = TRUE)

Enable Draggable Points

Description

Function to make points draggable

Usage

dragPoints(myIO, dragPoints = TRUE)

Arguments

Value

A modified myIO htmlwidget object with drag interaction enabled.

Examples

# Enable draggable points
myIO() |>
  addIoLayer(
    type = "point", color = "red", label = "pts",
    data = mtcars, mapping = list(x_var = "wt", y_var = "mpg")
  ) |>
  dragPoints()

DuckDB-WASM cache status

Description

DuckDB-WASM cache status

Usage

duckdb_wasm_status()

Value

A list with class 'myIO_duckdb_wasm_status' and fields 'installed' (logical), 'version' (chr or NA), 'cache_dir' (chr), 'size_bytes' (numeric).

Examples

duckdb_wasm_status()

Expand a grouped data frame into per-group layers

Description

When a grouped_df (from dplyr::group_by()) is passed to addIoLayer(), this function splits the data by group and recursively calls addIoLayer() once per group, assigning auto-colors from the Okabe-Ito palette.

Usage

expand_grouped_df(myIO, type, color, label, data, mapping, transform, options)

Arguments

Value

The modified myIO widget with one layer per group.

Flip Chart Axes

Description

Function to flip the x and y axes

Usage

flipAxis(myIO, flipAxis = TRUE)

Arguments

Value

A modified myIO htmlwidget object with axes flipped.

Examples

# Flip the axes for a horizontal bar chart
myIO() |>
  addIoLayer(
    type = "bar", color = "steelblue", label = "bars",
    data = mtcars, mapping = list(x_var = "wt", y_var = "mpg")
  ) |>
  flipAxis()

Install the DuckDB-WASM binary for large-dataset virtualization

Description

Downloads and verifies the DuckDB-WASM runtime into a user-local cache so the in-browser big-data engine is available for subsequent widgets. This follows the keras3 / torch / reticulate pattern: the binary is NOT bundled with the R package and is not required for small-data use.

Usage

install_duckdb_wasm(
  version = NULL,
  from = NULL,
  force = FALSE,
  quiet = !interactive()
)

Arguments

Value

Invisibly returns the cache path where the binary was installed.

Examples

## Not run: 
# Downloads ~22 MB from the upstream mirror into the user cache.
install_duckdb_wasm()

## End(Not run)

Link Charts for Cross-Selection

Description

A convenience wrapper that sets matching link config on multiple widgets so that brush selections propagate between them. Unlike setLinked, this does not require Crosstalk — it uses a shared group identifier and key column to coordinate selections across charts rendered in the same page.

Usage

linkCharts(..., on, group = NULL, cursor = FALSE, cursorAxis = "x")

Arguments

Value

A list of modified myIO widgets with matching link config.

Examples

w1 <- myIO() |>
  addIoLayer(type = "point", label = "scatter",
    data = mtcars, mapping = list(x_var = "wt", y_var = "mpg"))
w2 <- myIO() |>
  addIoLayer(type = "bar", label = "bars",
    data = mtcars, mapping = list(x_var = "cyl", y_var = "mpg"))
linked <- linkCharts(w1, w2, on = "cyl")

Create a myIO Chart Widget

Description

Create an interactive D3.js chart widget

Usage

myIO(
  data = NULL,
  width = "100%",
  height = "400px",
  elementId = NULL,
  title = NULL,
  sparkline = FALSE,
  engine = "auto",
  webgl_threshold = 50000L,
  unify_data_path = FALSE
)

Arguments

Value

An htmlwidget object of class myIO.

Examples

myIO(data = mtcars) |>
  setMargin(top = 40, bottom = 80, left = 60, right = 10)

Shiny Bindings for myIO

Description

Shiny Bindings for myIO

Usage

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

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

Arguments

Value

myIOOutput returns a Shiny UI element for placement in a UI definition. renderMyIO returns a Shiny render function for use in a server definition.

Examples

if (interactive()) {
  library(shiny)
  ui <- fluidPage(myIOOutput("chart"))
  server <- function(input, output) {
    output$chart <- renderMyIO({
      myIO(data = mtcars) |>
        addIoLayer(type = "point", label = "scatter",
          mapping = list(x_var = "wt", y_var = "mpg"))
    })
  }
  shinyApp(ui, server)
}

Diagnose myIO Rendering Errors

Description

Prints guidance on how to find the most recent JavaScript error from a myIO widget. In Shiny, errors are available as reactive inputs. Outside Shiny, errors appear in the browser's developer console.

Usage

myIO_last_error(outputId = NULL)

Arguments

Value

Invisibly returns NULL. Called for its side effect (printing diagnostic guidance).

Examples

myIO_last_error()
myIO_last_error("chart1")

Get myIO Chart Schema for LLM Tool Calling

Description

Get myIO Chart Schema for LLM Tool Calling

Usage

myio_chart_schema(type = NULL)

Arguments

Value

A list containing one chart schema or all chart schemas.

Examples

myio_chart_schema("boxplot")

Get a myIO Function Signature for LLM Tool Calling

Description

Get a myIO Function Signature for LLM Tool Calling

Usage

myio_function_signature(fn = NULL)

Arguments

Value

A character vector of argument names or a named list of signatures.

Examples

myio_function_signature("setAxisFormat")

List myIO Chart Types for LLM Tool Calling

Description

Returns chart type names from the generated myIO schema.

Usage

myio_list_chart_types()

Value

A character vector of chart type names.

Examples

head(myio_list_chart_types())

List myIO Functions for LLM Tool Calling

Description

List myIO Functions for LLM Tool Calling

Usage

myio_list_functions()

Value

A character vector of exported myIO function names.

Examples

head(myio_list_functions())

Validate a myIO Function Call

Description

Validate a myIO Function Call

Usage

myio_validate_call(fn, args = list())

Arguments

Value

A list with valid and errors. Errors use stable machine-readable code values.

Examples

myio_validate_call("setAxisFormat", list(axis_x = ".0f"))

Validate a myIO Chart Specification

Description

Validates a proposed chart specification against the generated myIO schema.

Usage

myio_validate_spec(spec, columns = NULL)

Arguments

Value

A list with valid and errors. Errors use stable machine-readable code values.

Examples

myio_validate_spec(list(
  type = "boxplot",
  mapping = list(column_var = "Species", value_var = "Sepal.Width")
))

Enable Click-to-Annotate

Description

Enables annotation mode where clicking a data point opens a label input. Annotations are stored as data and can be exported or accessed as a Shiny reactive input.

Usage

setAnnotation(myIO, labels = NULL, colors = NULL, mode = "click")

Arguments

Value

A modified myIO htmlwidget object with annotation enabled.

Examples

myIO(data = mtcars) |>
  addIoLayer(
    type = "point", label = "pts",
    mapping = list(x_var = "wt", y_var = "mpg")
  ) |>
  setAnnotation(labels = c("outlier", "normal"))

Set Axis Format

Description

Sets axis for x axis, y axis, and/or tool tip

Usage

setAxisFormat(
  myIO,
  xAxis = NULL,
  yAxis = NULL,
  toolTip = NULL,
  xLabel = NULL,
  yLabel = NULL
)

Arguments

Value

A modified myIO htmlwidget object with updated axis format configuration. with options set for the tooltip formats

Examples

# Set axis formats using d3.js format strings
myIO() |> setAxisFormat(xAxis = ".0f", yAxis = ".1f")

# Set axis labels
myIO() |> setAxisFormat(xLabel = "Weight (lbs)", yLabel = "MPG")

# Label-only calls preserve previously configured formats
myIO() |> setAxisFormat(yAxis = ".2f") |> setAxisFormat(yLabel = "Rate")

Set Axis Limits

Description

Sets the minimum and maximum values for chart axes

Usage

setAxisLimits(
  myIO,
  xlim = list(min = NULL, max = NULL),
  ylim = list(min = NULL, max = NULL)
)

Arguments

Value

A modified myIO htmlwidget object with updated axis limits.

Examples

# Set x axis limits
myIO() |> setAxisLimits(xlim = list(min = 0, max = 100))

# Set both axis limits
myIO() |> setAxisLimits(
  xlim = list(min = 0, max = 50),
  ylim = list(min = -10, max = 200)
)

Attach a big-data source to a myIO widget

Description

'setBigData()' declares the data source that a myIO widget should use for large-dataset rendering and linked-selection coordination.

Usage

setBigData(widget, source, rowkey_col = NULL, ...)

Arguments

Details

This function writes the 'x.bigdata.*' payload fields consumed by the widget's large-dataset virtualization path and follows its row-key contract. DBI sources are stored as an internal session-scoped marker in 'x.bigdata$dbi_handle_internal'; render-time source registration is handled by the source registry phase.

Value

A modified myIO htmlwidget object.

Examples

myIO(data = mtcars) |>
  setBigData(mtcars)

myIO() |>
  setBigData("data/large.parquet", schema = c("id", "x", "y"), rowkey_col = "id")

if (requireNamespace("duckdb", quietly = TRUE)) {
  con <- DBI::dbConnect(duckdb::duckdb())
  obs <- data.frame(id = seq_len(nrow(mtcars)), mpg = mtcars$mpg)
  DBI::dbWriteTable(con, "observations", obs)
  myIO() |>
    setBigData(con, table = "observations", rowkey_col = "id")
  DBI::dbDisconnect(con, shutdown = TRUE)
}

Enable Brush Selection

Description

Enables rectangle brush selection on the chart. When a user drags to select a region, the selected data points are available as a reactive input in Shiny or exportable in static HTML.

Usage

setBrush(myIO, direction = "xy", on_select = "highlight")

Arguments

Value

A modified myIO htmlwidget object with brush interaction enabled.

Examples

myIO(data = mtcars) |>
  addIoLayer(
    type = "point", label = "pts",
    mapping = list(x_var = "wt", y_var = "mpg")
  ) |>
  setBrush()

Set Color Scheme

Description

Sets color scheme for a chart and the category names (optional)

Usage

setColorScheme(myIO, colorScheme = NULL, setCategories = NULL)

Arguments

Value

A modified myIO htmlwidget object with updated color scheme.

Examples

# Set a custom color scheme
myIO() |> setColorScheme(colorScheme = list("red", "blue", "green"))

# Set colors with category labels
myIO() |> setColorScheme(
  colorScheme = list("steelblue", "orange"),
  setCategories = c("Group A", "Group B")
)

Configure Export Options

Description

Controls which export buttons appear in the chart toolbar.

Usage

setExportOptions(
  myIO,
  png = TRUE,
  svg = TRUE,
  pdf = TRUE,
  clipboard = TRUE,
  csv = TRUE,
  title = NULL
)

Arguments

Value

Modified myIO widget.

Examples

myIO(iris) |>
  addIoLayer("point", label = "pts",
             mapping = list(x_var = "Sepal.Length", y_var = "Sepal.Width")) |>
  setExportOptions(svg = TRUE, clipboard = TRUE, pdf = FALSE)

Set Faceting (Small Multiples)

Description

Splits the chart into a grid of panels, one per unique value of the faceting variable. Each panel shows the same layers filtered to that subset of the data.

Usage

setFacet(
  myIO,
  var,
  ncol = NULL,
  min_width = 200,
  scales = "fixed",
  label_position = "top"
)

Arguments

Value

Modified myIO widget.

Examples

myIO(iris) |>
  addIoLayer("point", label = "pts",
             mapping = list(x_var = "Sepal.Length", y_var = "Sepal.Width")) |>
  setFacet("Species", ncol = 3)

Set Layer Opacity

Description

Set Layer Opacity

Usage

setLayerOpacity(myIO, label, opacity)

Arguments

Value

A modified myIO htmlwidget object.

Examples

myIO(iris) |>
  addIoLayer("point", label = "pts",
             mapping = list(x_var = "Sepal.Length", y_var = "Sepal.Width")) |>
  setLayerOpacity("pts", 0.5)

Enable Linked Brushing via Crosstalk

Description

Connects the chart to a Crosstalk SharedData object so that brush selections propagate to other linked widgets.

Usage

setLinked(
  myIO,
  shared_data,
  mode = "both",
  filter = FALSE,
  key = NULL,
  group = NULL,
  cursor = FALSE,
  cursorAxis = "x"
)

Arguments

Value

A modified myIO htmlwidget with Crosstalk linking.

Examples

if (interactive() && requireNamespace("crosstalk", quietly = TRUE)) {
  shared <- crosstalk::SharedData$new(mtcars, key = ~rownames(mtcars))
  myIO() |>
    addIoLayer(
      type = "point", label = "scatter",
      data = shared$data(), mapping = list(x_var = "wt", y_var = "mpg")
    ) |>
    setLinked(shared)
}

Toggle Linked Cursor Sync on a myIO Widget

Description

Enables or disables synchronized hover crosshair across linked charts. Composable with linkCharts and setLinked via the pipe: call after linking to opt into cursor sync without re-linking. Preserves any existing interactions$linked configuration.

Usage

setLinkedCursor(myIO, enabled = TRUE, axis = "x")

Arguments

Value

A modified myIO htmlwidget.

Examples

w1 <- myIO() |>
  addIoLayer(type = "point", label = "a",
    data = mtcars, mapping = list(x_var = "wt", y_var = "mpg"))
w2 <- myIO() |>
  addIoLayer(type = "point", label = "b",
    data = mtcars, mapping = list(x_var = "hp", y_var = "mpg"))
linked <- linkCharts(w1, w2, on = "cyl")
linked[[1]] <- setLinkedCursor(linked[[1]])
linked[[2]] <- setLinkedCursor(linked[[2]])

Set Chart Margins

Description

Sets margins for the top, bottom, left, and right sides of the chart

Usage

setMargin(myIO, top = 20, bottom = 40, left = 50, right = 50)

Arguments

Value

A modified myIO htmlwidget object with updated margin configuration.

Examples

# Set custom margins
myIO() |> setMargin(top = 50, bottom = 80, left = 60, right = 20)

Set Reference Lines

Description

Sets x and y reference lines

Usage

setReferenceLines(myIO, xRef = 0, yRef = 0)

Arguments

Value

A modified myIO htmlwidget object with reference lines added.

Examples

# Add reference lines at x=5 and y=20
myIO() |> setReferenceLines(xRef = 5, yRef = 20)

Add a Parameter Slider (Shiny Only)

Description

Adds a slider control below the chart that adjusts a transform option and triggers reactive re-rendering in Shiny.

Usage

setSlider(myIO, param, label, min, max, value, step = NULL, debounce = 200)

Arguments

Value

A modified myIO htmlwidget with slider config attached.

Examples

## Not run: 
# In a Shiny server function:
output$chart <- renderMyIO({
  myIO(data = mtcars) |>
    addIoLayer(
      type = "regression", label = "fit",
      mapping = list(x_var = "wt", y_var = "mpg"),
      options = list(ci_level = 0.95)
    ) |>
    setSlider("ci_level", "Confidence level", 0.80, 0.99, 0.95, 0.01)
})

## End(Not run)

Set Chart Theme

Description

Sets chart theme tokens using CSS custom properties

Usage

setTheme(
  myIO,
  text_color = NULL,
  grid_color = NULL,
  bg = NULL,
  font = NULL,
  mode = NULL,
  preset = NULL,
  overrides = list(),
  ...
)

Arguments

Value

A modified myIO htmlwidget object with updated theme configuration.

Examples

myIO() |>
  setTheme(text_color = "#222222", grid_color = "#d9d9d9")

myIO() |>
  setTheme(mode = "dark", bg = "#1a1a2e")

Set Chart Title

Description

Sets the title rendered inside the myIO widget SVG.

Usage

setTitle(myIO, title = NULL)

Arguments

Value

A modified myIO htmlwidget object.

Examples

myIO() |>
  setTitle("Miles per gallon") |>
  addIoLayer("point", label = "cars",
             data = mtcars,
             mapping = list(x_var = "wt", y_var = "mpg"))

Set Toggle Interaction

Description

Sets toggle options for y_var and adds a toggle button for chart

Usage

setToggle(myIO, variable, format = NULL)

Arguments

Value

A modified myIO htmlwidget object with toggle interaction configured.

Examples

# Add a toggle button to switch y variable
myIO() |> setToggle(variable = "Percent", format = ".0%")

Set Tooltip Options

Description

Generic function for setting tool tip options for a chart

Usage

setToolTipOptions(myIO, suppressY = NULL)

Arguments

Value

A modified myIO htmlwidget object with updated tooltip options.

Examples

# Suppress the y value in tooltips
myIO() |> setToolTipOptions(suppressY = TRUE)

Set Transition Speed

Description

Sets transition speeds across the chart (set to 0 to suppress)

Usage

setTransitionSpeed(myIO, speed)

Arguments

Value

A modified myIO htmlwidget object with updated transition speed.

Examples

# Set transition speed to 500ms
myIO() |> setTransitionSpeed(speed = 500)

# Disable transitions
myIO() |> setTransitionSpeed(speed = 0)

Raise a DuckDB-WASM missing-runtime condition

Description

Raise a DuckDB-WASM missing-runtime condition

Usage

stop_duckdb_wasm_missing()

Value

Does not return; always throws a condition of class myIOError_duckdb_wasm_missing.

Suppress Axis Display

Description

Suppresses axes from printing

Usage

suppressAxis(myIO, xAxis = NULL, yAxis = NULL)

Arguments

Value

A modified myIO htmlwidget object with axis display suppressed.

Examples

# Suppress both axes
myIO() |> suppressAxis(xAxis = TRUE, yAxis = TRUE)

# Suppress only the x axis
myIO() |> suppressAxis(xAxis = TRUE)

Suppress Legend Display

Description

Suppresses legend from printing

Usage

suppressLegend(myIO, suppressLegend = TRUE)

Arguments

Value

A modified myIO htmlwidget object with legend display suppressed.

Examples

# Hide the legend
myIO() |> suppressLegend()

Kaplan-Meier survival transform

Description

Computes the KM estimator, Greenwood CI, and censoring indicators from raw time-to-event data. No dependency on the survival package.

Usage

transform_survfit(data, mapping, options = list())

Arguments

Value

List with 'data' (data.frame) and 'meta'.