Create Interactive Trelliscope Displays

Authors: Ryan Hafen [aut, cre],Barret Schloerke [aut]

Version: 0.1.8

License: BSD_3_clause + file LICENSE

Description

Trelliscope is a scalable, flexible, interactive approach to visualizing data. This package provides methods that make it easy to create a Trelliscope display specification for TrelliscopeJS. High-level functions are provided for creating displays from within dplyr or ggplot2 workflows. Low-level functions are also provided for creating new interfaces.

Depends

R (>= 3.2.3)

Imports

dplyr, purrr, tidyr, htmltools, DistributionUtils, grDevices, digest, jsonlite, ggplot2 (> 2.1.0), base64enc, htmlwidgets, graphics, progress, utils, knitr, webshot

Suggests

rbokeh, plotly, Cairo, testthat, covr, gapminder, housingData, packagedocs

Trelliscope Functions

trelliscope

Create a Trelliscope Display

Usage

trelliscope(x, name, group = "common", panel_col = NULL, desc = "", md_desc = "", path, height = 500, width = 500, auto_cog = TRUE, state = NULL, nrow = 1, ncol = 1, jsonp = TRUE, self_contained = FALSE, thumb = FALSE)

Arguments

x
an object to create at trelliscope display for
name
name of the display
group
group that the display belongs to
panel_col
optional string specifying the column to use for panels (if there are multiple plot columns in x)
desc
optional text description of the display
md_desc
optional string of markdown that will be shown in the viewer for additional context about the display
path
the base directory of the trelliscope application
height
height in pixels of each panel
width
width in pixels of each panel
auto_cog
should auto cogs be computed (if possible)?
state
the initial state the display will open in
nrow
the number of rows of panels to display by default
ncol
the number of columns of panels to display by default
jsonp
should json for display object be jsonp (TRUE) or json (FALSE)?
self_contained
should the Trelliscope display be a self-contained html document? (see note)
thumb
should a thumbnail be created?

Note

Note that self_contained is severely limiting and should only be used in cases where you would either like your display to show up in the RStudio viewer pane, in an interactive R Markdown Notebook, or in a self-contained R Markdown html document.

Examples

## Not run: 
# library(dplyr)
# library(rbokeh)
# library(ggplot2)
# 
# # dplyr + rbokeh
# d <- mpg %>%
#   group_by(manufacturer, class) %>%
#   summarise(
#     panel = panel(
#       figure(xlab = "City mpg", ylab = "Highway mpg") %>%
#         ly_points(cty, hwy)))
# 
# d %>% trelliscope(name = "city_vs_highway_mpg")
# 
# # if you want to use in RStudio Viewer or RMarkdown Notebook, use self_containedd
# # (this will hopefully change, and you should avoid self_contained whenever possible)
# d %>% trelliscope(name = "city_vs_highway_mpg", self_contained = TRUE)
# 
# # set default layout
# d %>% trelliscope(name = "city_vs_highway_mpg", nrow = 2, ncol = 3)
# 
# # set the output path for where files will be stored
# d %>% trelliscope(name = "city_vs_highway_mpg", path = "mydisplays")
# 
# # multiple displays can be added to the same path and all will be available in the viewer
# d %>% trelliscope(name = "city_vs_highway_mpg2", path = "mydisplays")
# 
# # ordering the data frame will set default sort order of the display
# d %>%
#   arrange(-mean_city_mpg) %>%
#   trelliscope(name = "city_vs_highway_mpg")
# 
# # dplyr + ggplot2
# mpg %>%
#   group_by(manufacturer, class) %>%
#   summarise(
#     panel = panel(
#       qplot(cty, hwy) + xlab("cty") + ylab("hwy") +
#         xlim(7, 37) + ylim(9, 47) + theme_bw())) %>%
#   trelliscope(name = "dplyr_gg")
# 
# # computing additional cognostics
# mpg %>%
#   group_by(manufacturer, class) %>%
#   summarise(
#     mean_city_mpg = mean(cty),
#     mean_hwy_mpg = mean(hwy),
#     most_common_drv = tail(names(table(drv)), 1),
#     panel = panel(
#       figure(xlab = "City mpg", ylab = "Highway mpg",
#         xlim = c(9, 47), ylim = c(7, 37)) %>%
#         ly_points(cty, hwy,
#           hover = data_frame(model = paste(year, model),
#           cty = cty, hwy = hwy)))) %>%
#   trelliscope(name = "city_vs_highway_mpg", nrow = 1, ncol = 2)
# 
# # computing additional cognostics explicitly using cog()
# # so we can specify descriptions, etc.
# mpg %>%
#   group_by(manufacturer, class) %>%
#   summarise(
#     mean_city_mpg = cog(mean(cty), desc = "Mean city mpg"),
#     mean_hwy_mpg = cog(mean(hwy), desc = "Mean highway mpg"),
#     most_common_drv = cog(tail(names(table(drv)), 1), desc = "Most common drive type"),
#     panel = panel(
#       figure(xlab = "City mpg", ylab = "Highway mpg",
#         xlim = c(9, 47), ylim = c(7, 37)) %>%
#         ly_points(cty, hwy,
#           hover = data_frame(model = paste(year, model),
#           cty = cty, hwy = hwy)))) %>%
#   trelliscope(name = "city_vs_highway_mpg", nrow = 1, ncol = 2)
# ## End(Not run)

facet_trelliscope

Facet Trelliscope

Usage

facet_trelliscope(..., nrow = 1, ncol = 1, name = NULL, group = "common", desc = "", md_desc = "", path = NULL, height = 500, width = 500, state = NULL, jsonp = TRUE, as_plotly = FALSE, plotly_args = NULL, self_contained = FALSE, thumb = TRUE)

Arguments

all parameters passed onto ggplot2::facet_wrap
nrow
the number of rows of panels to display by default
ncol
the number of columns of panels to display by default
name
name of the display
group
group that the display belongs to
desc
description of the display
md_desc
optional string of markdown that will be shown in the viewer for additional context about the display
path
the base directory of the trelliscope application
height
height in pixels of each panel
width
width in pixels of each panel
state
the initial state the display will open in
jsonp
should json for display object be jsonp (TRUE) or json (FALSE)?
as_plotly
should the panels be written as plotly objects?
plotly_args
optinal named list of arguments to send to ggplotly
self_contained
should the Trelliscope display be a self-contained html document? (see note)
thumb
should a thumbnail be created?

Note

Note that self_contained is severely limiting and should only be used in cases where you would either like your display to show up in the RStudio viewer pane, in an interactive R Markdown Notebook, or in a self-contained R Markdown html document.

Examples

## Not run: 
# library(ggplot2)
# 
# # basically swap out facet_wrap for facet_trelliscope
# qplot(cty, hwy, data = mpg) +
#   facet_trelliscope(~ class + manufacturer)
# 
# # not required, but if you set labels, these will be added as
# # descriptions to the cognostics that are automatically computed
# mpg <- set_labels(mpg, mpg_labels)
# 
# qplot(cty, hwy, data = mpg) +
#   xlim(7, 37) + ylim(9, 47) + theme_bw() +
#   facet_trelliscope(~ manufacturer + class, nrow = 2, ncol = 4)
# 
# # using plotly
# library(plotly)
# qplot(cty, hwy, data = mpg) +
#   xlim(7, 37) + ylim(9, 47) + theme_bw() +
#   facet_trelliscope(~ manufacturer + class, nrow = 2, ncol = 4, as_plotly = TRUE)
# 
# qplot(class, cty, data = mpg, geom = c("boxplot", "jitter")) +
#   facet_trelliscope(~ class, ncol = 7, height = 800, width = 200,
#     state = list(sort = list(sort_spec("cty_mean")))) +
#   ylim(7, 37) + theme_bw()
# ## End(Not run)

print.facet_trelliscope

Print facet trelliscope object

Usage

"print"(x, ...)

Arguments

x
plot object
ignored

Cognostics

cog

Cast Column as a Cognostic

Cast a column of a cognostics data frame as a cognostic object

Usage

cog(val = NULL, desc = "", group = "common", type = NULL, default_label = FALSE, default_active = TRUE, filterable = TRUE, sortable = TRUE, log = NULL)

Arguments

val
a scalar value (numeric, characer, date, etc.)
desc
a description for this cognostic value
group
optional categorization of the cognostic for organizational purposes in the viewer (currently not implemented in the viewer)
type
the desired type of cognostic you would like to compute (see details)
default_label
should this cognostic be used as a panel label in the viewer by default?
default_active
should this cognostic be active (available for sort / filter / sample) by default?
filterable
should this cognostic be filterable? Default is TRUE. It can be useful to set this to FALSE if the cognostic is categorical with many unique values and is only desired to be used as a panel label.
sortable
should this cognostic be sortable?
log
when being used in the viewer for visual univariate and bivariate filters, should the log be computed? Useful when the distribution of the cognostic is very long-tailed or has large outliers. Can either be a logical or a positive integer indicating the base.

Value

object of class “cog”

Details

Different types of cognostics can be specified through the type argument that will affect how the user is able to interact with those cognostics in the viewer. This can usually be ignored because it will be inferred from the implicit data type of val. But there are special types of cognostics, such as geographic coordinates and relations (not implemented) that can be specified as well. Current possibilities for type are “key”, “integer”, “numeric”, “factor”, “date”, “time”, “href”.

Examples

## Not run: 
# mpg %>%
#   group_by(manufacturer, class) %>%
#   summarise(
#     mean_city_mpg = cog(mean(cty), desc = "Mean city mpg"),
#     mean_hwy_mpg = cog(mean(hwy), desc = "Mean highway mpg"),
#     most_common_drv = cog(tail(names(table(drv)), 1), desc = "Most common drive type"),
#     panel = panel(
#       figure(xlab = "City mpg", ylab = "Highway mpg",
#         xlim = c(9, 47), ylim = c(7, 37)) %>%
#         ly_points(cty, hwy,
#           hover = data_frame(model = paste(year, model),
#           cty = cty, hwy = hwy)))) %>%
#   trelliscope(name = "city_vs_highway_mpg", nrow = 1, ncol = 2)
# ## End(Not run)

cog_href

Href Cognostic

Create href to be used as cognostics in a trelliscope display

Usage

cog_href(x, desc = "link", group = "common", default_label = FALSE, default_active = FALSE, filterable = FALSE, sortable = FALSE, log = FALSE)

Arguments

x
URL to link to
desc, group, default_label, default_active, filterable, sortable, log
arguments passed to cog

Examples

## Not run: 
# library(dplyr)
# library(rbokeh)
# iris %>%
#   group_by(Species) %>%
#   summarise(
#     wiki_link = cog_href(paste0("https://en.wikipedia.org/wiki/Iris_",
#       tolower(Species))[1], default_label = TRUE,
#       desc = "link to species on wikipedia"),
#     panel = panel(figure(xlab = "Sepal Length", ylab = "Sepal Width") %>%
#       ly_points(Sepal.Length, Sepal.Width))) %>%
#   trelliscope(name = "iris_species", ncol = 3)
# ## End(Not run)

See also

cog

cogs

Cogs Wrapper Function

Usage

cogs(.x, .f, ...)

Arguments

.x
a list or atomic vector (see map for details)
.f
a function, formula, or atomic vector (see map for details)
additional arguments passed on to .f (see map for details)

Details

See map

Examples

## Not run: 
# library(dplyr)
# library(tidyr)
# ggplot2::mpg %>%
#   group_by(manufacturer, class) %>%
#   nest() %>%
#   mutate(
#     additional_cogs = map_cog(data,
#       ~ data_frame(
#         max_city_mpg = cog(max(.x$cty), desc = "Max city mpg"),
#         min_city_mpg = cog(min(.x$cty), desc = "Min city mpg"))),
#     panel = map_plot(data, ~ figure(xlab = "City mpg", ylab = "Highway mpg") %>%
#       ly_points(cty, hwy, data = .x))) %>%
#   trelliscope(name = "city_vs_highway_mpg", nrow = 1, ncol = 2)
# ## End(Not run)

auto_cogs

Compute automatic cognostics

Usage

auto_cogs(data)

Arguments

data
a list of data frames (one per subset), a grouped data frame, or a nested data frame

Value

If the input is a list of data frames, the return value is a list of data frames containing the cognostics. If the input is a grouped or nested df, the result will be a nested df with a new column containing the cognostics.

See also

trelliscope

Helpers

panel

Panel Wrapper Function Wrapper function to specify a plot object for a panel for use in dplyr summarise()

Usage

panel(x)

Arguments

x
a plot object

Examples

## Not run: 
# library(rbokeh)
# library(dplyr)
# ggplot2::mpg %>%
#   group_by(manufacturer, class) %>%
#   summarise(
#     panel = panel(
#       figure(xlab = "City mpg", ylab = "Highway mpg") %>%
#         ly_points(cty, hwy)))
# ## End(Not run)

panels

Panels Wrapper Function

Usage

panels(.x, .f, ...)

Arguments

.x
a list or atomic vector (see map for details)
.f
a function, formula, or atomic vector (see map for details)
additional arguments passed on to .f (see map for details)

Details

See map

Examples

## Not run: 
# library(dplyr)
# library(tidyr)
# ggplot2::mpg %>%
#   group_by(manufacturer, class) %>%
#   nest() %>%
#   mutate(panel = map_plot(data,
#     ~ figure(xlab = "City mpg", ylab = "Highway mpg") %>%
#         ly_points(cty, hwy, data = .x))) %>%
#   trelliscope(name = "city_vs_highway_mpg")
# ## End(Not run)

set_labels

Set labels for a data frame

Usage

set_labels(dat, label_list)

Arguments

dat
a data frame to apply labels to
label_list
a named list with names matching those of dat and values being labels

Value

data frame with labels attached as attributes (attached to each column and named “label”)

sort_spec

Specify how a display should be sorted

Usage

sort_spec(name, dir = "asc")

Arguments

name
variable name to sort on
dir
direction to sort (asc or desc)

Low-level Functions

prepare_display

Set up all auxilliary files needed for a Trelliscope app

Usage

prepare_display(base_path, id, self_contained = FALSE, jsonp = TRUE, pb = NULL)

Arguments

base_path
the base directory of the trelliscope application
id
a unique id for the application
self_contained
should the Trelliscope display be a self-contained html document?
jsonp
should json for display list and app config be jsonp (TRUE) or json (FALSE)?
pb
optional progress bar object to pass in and use to report progress

update_display_list

Update Trelliscope app display list file

Usage

update_display_list(base_path, jsonp = TRUE)

Arguments

base_path
the base directory of the trelliscope application
jsonp
should json for display list be jsonp (TRUE) or json (FALSE)?

write_cognostics

Write cognostics data for a display in a Trelliscope app

Usage

write_cognostics(cogdf, base_path, id, name, group = "common", jsonp = TRUE)

Arguments

cogdf
a data frame of cognostics, prepared with as_cognostics
base_path
the base directory of the trelliscope application
id
a unique id for the application
name
name of the display
group
group that the display belongs to
jsonp
should json for cognostics be jsonp (TRUE) or json (FALSE)?

write_config

Write Trelliscope app configuration file

Usage

write_config(base_path, id, self_contained = FALSE, jsonp = TRUE)

Arguments

base_path
the base directory of the trelliscope application
id
a unique id for the application
self_contained
should the Trelliscope display be a self-contained html document?
jsonp
should json for app config be jsonp (TRUE) or json (FALSE)?

write_display_obj

Write a “display object” file for a Trelliscope app

Usage

write_display_obj(cogdf, panel_example, base_path, id, name, group = "common", desc = "", height = 500, width = 500, md_desc = "", state = NULL, jsonp = TRUE, panel_img_col = NULL, self_contained = FALSE, thumb = TRUE, pb = NULL)

Arguments

cogdf
a data frame of cognostics, prepared with as_cognostics
panel_example
an example object of one panel of a display (can be trellis, ggplot2, or htmlwidget object)
base_path
the base directory of the trelliscope application
id
a unique id for the application
name
name of the display
group
group that the display belongs to
desc
description of the display
height
height in pixels of each panel
width
width in pixels of each panel
md_desc
optional string of markdown that will be shown in the viewer for additional context about the display
state
the initial state the display will open in
jsonp
should json for display object be jsonp (TRUE) or json (FALSE)?
panel_img_col
which column (if any) is a panel image column?
self_contained
should the Trelliscope display be a self-contained html document?
thumb
should a thumbnail be created?
pb
optional progress bar object to pass in and use to report progress

write_panel

Write a plot object as a panel in a Trelliscope display

Usage

write_panel(plot_object, key, base_path, name, group = "common", width, height, jsonp = TRUE)

Arguments

plot_object
a plot object to be written (can be trellis, ggplot2, or htmlwidget)
key
a string identifying the panel key, which will be used as the panel file name and which the panelKey column of the cognostics data frame should point to
base_path
the base directory of the trelliscope application
name
name of the display that the panel belongs to
group
group name of the display that the panel belongs to
width
width in pixels of each panel
height
height in pixels of each panel
jsonp
should json for panel be jsonp (TRUE) or json (FALSE)?

write_panels

Write a list of plot objects as panels in a Trelliscope display

Usage

write_panels(plot_list, base_path, name, group = "common", width = 500, height = 500, jsonp = TRUE, progress = TRUE, pb = NULL)

Arguments

plot_list
a named list of plot objects to be written as panels (objects can be trellis, ggplot2, or htmlwidget) with the list names being the keys for the panels
base_path
the base directory of the trelliscope application
name
name of the display that the panel belongs to
group
group name of the display that the panel belongs to
width
width in pixels of each panel
height
height in pixels of each panel
jsonp
should json for panels be jsonp (TRUE) or json (FALSE)?
progress
= TRUE
pb
optional progress bar object to pass in and use to report progress

as_cognostics

Cast a data frame as a cognostics data frame

Usage

as_cognostics(x, cond_cols, key_col = NULL, cog_desc = NULL, needs_key = TRUE, needs_cond = TRUE)

Arguments

x
a data frame
cond_cols
the column name(s) that comprise the conditioning variables
key_col
the column name that indicates the panel key
cog_desc
an optional named list of descriptions for the cognostics columns
needs_key
does the result need to have a “key” column?
needs_cond
does the result need to have conditioning variable columns?

Datasets

mpg_labels

Labels for ggplot2 “mpg” data

Usage

mpg_labels

Format

An object of class list of length 10.