perspectiveR: Interactive Pivot Tables and Visualizations with 'Perspective'

Description

An 'htmlwidgets' binding for the 'FINOS Perspective' https://perspective-dev.github.io/ library, a high-performance 'WebAssembly'-powered data visualization engine. Provides interactive pivot tables, cross-tabulations, and multiple chart types (bar, line, scatter, heatmap, and more) that run entirely in the browser. Supports self-service analytics with drag-and-drop column selection, group-by/split-by pivoting, filtering, sorting, aggregation, and computed expressions. Works in 'RStudio' Viewer, 'R Markdown', 'Quarto', and 'Shiny' with streaming data updates via proxy interface.

Author(s)

Maintainer: Eli Eydlin ilyabeydlin@gmail.com

See Also

Useful links:

• https://github.com/EydlinIlya/perspectiveR

• Report bugs at https://github.com/EydlinIlya/perspectiveR/issues

Create a Perspective Interactive Viewer

Description

Creates an interactive pivot table and visualization widget powered by the FINOS Perspective library. The viewer provides a self-service UI where users can interactively change chart types, group/split/filter/sort data, create computed columns, and configure aggregations.

Usage

perspective(
  data,
  columns = NULL,
  group_by = NULL,
  split_by = NULL,
  sort = NULL,
  filter = NULL,
  filter_op = NULL,
  expressions = NULL,
  aggregates = NULL,
  plugin = NULL,
  plugin_config = NULL,
  theme = "Pro Light",
  settings = TRUE,
  title = NULL,
  editable = FALSE,
  index = NULL,
  limit = NULL,
  use_arrow = FALSE,
  width = NULL,
  height = NULL,
  elementId = NULL
)

Arguments

Details

When used in a Shiny app, the following reactive inputs are available (where outputId is the ID passed to perspectiveOutput):

input$<outputId>_config

Fires when the user changes the viewer configuration (columns, pivots, filters, etc.).

input$<outputId>_click

Fires when the user clicks a cell or data point.

input$<outputId>_select

Fires when the user selects rows or data points.

input$<outputId>_update

Fires on each table data change when subscribed via psp_on_update.

input$<outputId>_export

Contains exported data after calling psp_export.

input$<outputId>_state

Contains saved viewer state after calling psp_save.

input$<outputId>_schema

Contains the table schema after calling psp_schema.

input$<outputId>_size

Contains the table row count after calling psp_size.

input$<outputId>_columns

Contains the table column names after calling psp_columns.

input$<outputId>_validate_expressions

Contains expression validation results after calling psp_validate_expressions.

Value

An htmlwidgets object that can be printed, included in R Markdown, Quarto documents, or Shiny apps.

Examples

# Basic data grid
perspective(mtcars)

# Bar chart grouped by cylinder count
perspective(mtcars, group_by = "cyl", plugin = "Y Bar")

# Filtered and sorted view
perspective(iris,
  columns = c("Sepal.Length", "Sepal.Width", "Species"),
  filter = list(c("Species", "==", "setosa")),
  sort = list(c("Sepal.Length", "desc"))
)

Shiny Output for Perspective Viewer

Description

Creates a Perspective viewer output element for use in a Shiny UI.

Usage

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

Arguments

Details

The following reactive inputs are available (where outputId is the ID you supply):

input$<outputId>_config

Viewer configuration changes.

input$<outputId>_click

Cell/data-point click events.

input$<outputId>_select

Row/data-point selection events.

input$<outputId>_update

Table data changes (requires psp_on_update).

input$<outputId>_export

Exported data (after psp_export).

input$<outputId>_state

Saved viewer state (after psp_save).

input$<outputId>_schema

Table schema (after psp_schema).

input$<outputId>_size

Table row count (after psp_size).

input$<outputId>_columns

Table column names (after psp_columns).

input$<outputId>_validate_expressions

Expression validation results (after psp_validate_expressions).

Value

A Shiny output element.

Examples

if (interactive()) {
library(shiny)
ui <- fluidPage(
  perspectiveOutput("viewer", height = "600px")
)
}

Create a Perspective Proxy Object for Shiny

Description

Creates a proxy object that can be used to update an existing Perspective viewer in a Shiny app without re-rendering the entire widget. Use this with psp_update, psp_replace, psp_clear, psp_restore, and psp_reset to modify the viewer.

Usage

perspectiveProxy(session, outputId)

Arguments

Value

A proxy object of class "perspective_proxy".

Examples

if (interactive()) {
server <- function(input, output, session) {
  output$viewer <- renderPerspective({
    perspective(mtcars)
  })

  observeEvent(input$add_data, {
    proxy <- perspectiveProxy(session, "viewer")
    psp_update(proxy, new_data)
  })
}
}

Clear All Data from a Perspective Viewer

Description

Removes all rows from the Perspective table (schema is preserved).

Usage

psp_clear(proxy)

Arguments

Value

The proxy object (invisibly), for chaining.

Examples

if (interactive()) {
proxy <- perspectiveProxy(session, "viewer")
psp_clear(proxy)
}

Get Table Column Names

Description

Requests the column names of the Perspective table. The result is delivered asynchronously to input$<outputId>_columns.

Usage

psp_columns(proxy)

Arguments

Value

The proxy object (invisibly), for chaining.

Examples

if (interactive()) {
proxy <- perspectiveProxy(session, "viewer")
psp_columns(proxy)
}

Export Data from a Perspective Viewer

Description

Requests data export from the current Perspective view. The result is delivered asynchronously to input$<outputId>_export.

Usage

psp_export(
  proxy,
  format = c("json", "csv", "columns", "arrow"),
  start_row = NULL,
  end_row = NULL,
  start_col = NULL,
  end_col = NULL
)

Arguments

Value

The proxy object (invisibly), for chaining.

Examples

if (interactive()) {
proxy <- perspectiveProxy(session, "viewer")
psp_export(proxy, format = "csv")
}

Subscribe to Table Update Events

Description

Enables or disables a subscription to table data changes. When enabled, every table.update() triggers input$<outputId>_update with a list containing timestamp, port_id, and source ("edit" for user edits, "api" for programmatic updates).

Usage

psp_on_update(proxy, enable = TRUE)

Arguments

Value

The proxy object (invisibly), for chaining.

Examples

if (interactive()) {
proxy <- perspectiveProxy(session, "viewer")
psp_on_update(proxy)
}

Remove Rows by Key from a Perspective Viewer

Description

Removes rows matching the given primary-key values from an indexed Perspective table. The table must have been created with an index column (see perspective).

Usage

psp_remove(proxy, keys)

Arguments

Value

The proxy object (invisibly), for chaining.

Examples

if (interactive()) {
proxy <- perspectiveProxy(session, "viewer")
psp_remove(proxy, keys = c("row1", "row2"))
}

Replace All Data in a Perspective Viewer

Description

Replaces the entire dataset in the Perspective table.

Usage

psp_replace(proxy, data, use_arrow = FALSE)

Arguments

Value

The proxy object (invisibly), for chaining.

Examples

if (interactive()) {
proxy <- perspectiveProxy(session, "viewer")
psp_replace(proxy, updated_data)
}

Reset Viewer to Default State

Description

Resets the Perspective viewer to its default configuration.

Usage

psp_reset(proxy)

Arguments

Value

The proxy object (invisibly), for chaining.

Examples

if (interactive()) {
proxy <- perspectiveProxy(session, "viewer")
psp_reset(proxy)
}

Restore Viewer Configuration

Description

Applies a configuration object to the Perspective viewer, changing columns, group_by, split_by, filters, sort, aggregates, plugin, etc.

Usage

psp_restore(proxy, config)

Arguments

Value

The proxy object (invisibly), for chaining.

Examples

if (interactive()) {
proxy <- perspectiveProxy(session, "viewer")
psp_restore(proxy, list(plugin = "Y Bar", group_by = list("cyl")))
}

Save Viewer State

Description

Requests the current viewer configuration (columns, pivots, filters, sort, plugin, etc.). The result is delivered asynchronously to input$<outputId>_state.

Usage

psp_save(proxy)

Arguments

Value

The proxy object (invisibly), for chaining.

Examples

if (interactive()) {
proxy <- perspectiveProxy(session, "viewer")
psp_save(proxy)
}

Get Table Schema

Description

Requests the schema (column names and types) of the Perspective table. The result is delivered asynchronously to input$<outputId>_schema.

Usage

psp_schema(proxy)

Arguments

Value

The proxy object (invisibly), for chaining.

Examples

if (interactive()) {
proxy <- perspectiveProxy(session, "viewer")
psp_schema(proxy)
}

Get Table Row Count

Description

Requests the number of rows in the Perspective table. The result is delivered asynchronously to input$<outputId>_size.

Usage

psp_size(proxy)

Arguments

Value

The proxy object (invisibly), for chaining.

Examples

if (interactive()) {
proxy <- perspectiveProxy(session, "viewer")
psp_size(proxy)
}

Update (Append) Data in a Perspective Viewer

Description

Sends new rows to be appended to the existing Perspective table.

Usage

psp_update(proxy, data, use_arrow = FALSE)

Arguments

Value

The proxy object (invisibly), for chaining.

Examples

if (interactive()) {
proxy <- perspectiveProxy(session, "viewer")
psp_update(proxy, new_data)
}

Validate Expressions

Description

Validates Perspective expression strings against the table without applying them. The result is delivered asynchronously to input$<outputId>_validate_expressions.

Usage

psp_validate_expressions(proxy, expressions)

Arguments

Value

The proxy object (invisibly), for chaining.

Examples

if (interactive()) {
proxy <- perspectiveProxy(session, "viewer")
psp_validate_expressions(proxy, expressions = c("\"col1\" + \"col2\""))
}

Render a Perspective Viewer in Shiny

Description

Server-side rendering function for the Perspective widget.

Usage

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

Arguments

Value

A Shiny render function.

Examples

if (interactive()) {
server <- function(input, output) {
  output$viewer <- renderPerspective({
    perspective(mtcars, group_by = "cyl", plugin = "Y Bar")
  })
}
}

Run a perspectiveR Example App

Description

Launches a bundled Shiny example app demonstrating the perspectiveR widget.

Usage

run_example(example = NULL, ...)

Arguments

Value

If example is NULL, a character vector of available example names (invisibly). Otherwise, no return value; called for the side effect of launching a Shiny app.

Examples

# List available examples
run_example()

# Launch the demo app
if (interactive()) {
run_example("shiny-basic")
}