Create a Perspective Interactive Viewer — perspective • perspectiveR

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

data: A data.frame or matrix to display.
columns: Character vector of column names to show. If NULL, all columns are shown.
group_by: Character vector of column names to group rows by (row pivots).
split_by: Character vector of column names to split columns by (column pivots).
sort: A list of two-element vectors, each containing a column name and a direction ("asc", "desc", "col asc", "col desc", "asc abs", "desc abs", "col asc abs", "col desc abs"). For example: list(c("mpg", "desc")).
filter: A list of three-element vectors, each containing a column name, an operator ("==", "!=", ">", "<", ">=", "<=", "begins with", "contains", "ends with", "in", "not in", "is null", "is not null"), and a value. For example: list(c("cyl", "==", "6")).
filter_op: Character string controlling how multiple filters are combined: "and" (default) or "or". If NULL, the Perspective default ("and") is used.
expressions: Character vector of Perspective expression strings for computed columns. For example: c('"Profit" / "Sales"').
aggregates: A named list mapping column names to aggregate functions. For example: list(mpg = "avg", hp = "sum").
plugin: Character string specifying the visualization plugin. Options include: "Datagrid", "Y Bar", "X Bar", "Y Line", "X/Y Line", "Y Area", "Y Scatter", "XY Scatter", "Treemap", "Sunburst", "Heatmap".
plugin_config: A list of plugin-specific configuration options.
theme: Character string specifying the CSS theme. Options: "Pro Light", "Pro Dark", "Monokai", "Solarized Light", "Solarized Dark", "Vaporwave", "Dracula", "Gruvbox", "Gruvbox Dark". Default is "Pro Light".
settings: Logical; whether to show the settings/configuration panel sidebar. Default TRUE. This is the interactive UI where users drag-and-drop columns, change chart types, add filters, etc.
title: Character string for the viewer title. If NULL, no title is shown.
editable: Logical; whether the data in the grid is user-editable. Default FALSE.
index: Character string naming a column to use as the table's primary key. When set, psp_update() performs upserts (matching rows are updated instead of appended) and psp_remove() can delete rows by key. Must be the name of a column present in data. Default NULL (no index).
limit: Single positive integer specifying the maximum number of rows the table will hold. When new rows are added beyond this limit, the oldest rows are removed (rolling window). Mutually exclusive with index. Default NULL (no limit).
use_arrow: Logical; if TRUE, serialize data using Arrow IPC format (base64-encoded) for better performance with large datasets. Requires the arrow package. Default FALSE.
width: Widget width (CSS string or numeric pixels).
height: Widget height (CSS string or numeric pixels).
elementId: Optional explicit element ID for the widget.

Value

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

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.

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"))
)