| Title: | Explore Your Data with Interactive Figures |
|---|---|
| Description: | A framework for creating interactive figures for data exploration. All plots are automatically linked and support several kinds of interactive features, including selection, zooming, panning, and parameter manipulation. The figures can be interacted with either manually, using a mouse and a keyboard, or by running code from inside an active R session. |
| Authors: | Adam Bartonicek [aut, cre, cph] |
| Maintainer: | Adam Bartonicek <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.4 |
| Built: | 2024-11-20 08:26:42 UTC |
| Source: | https://github.com/bartonicek/plotscaper |
This function adds a barplot to a plotscaper scene or schema.
add_barplot(x, variables = NULL, options = NULL)add_barplot(x, variables = NULL, options = NULL)
x |
A |
variables |
A vector of variable names: one discrete (required), one continuous (optional) |
options |
A list of options |
The scene or schema back, with the plot added appropriately
This function adds a mirrored barplot to a plotscaper scene or schema.
add_bibarplot(x, variables = NULL, options = NULL)add_bibarplot(x, variables = NULL, options = NULL)
x |
A |
variables |
A vector of variable names: one discrete (required), one or two continuous (required) |
options |
A list of options |
The scene or schema back, with the plot added appropriately
This function adds a fluctuation diagram to a plotscaper scene or schema.
add_fluctplot(x, variables = NULL, options = NULL)add_fluctplot(x, variables = NULL, options = NULL)
x |
A |
variables |
A vector of variable names: two discrete (required), one continuous (optional) |
options |
A list of options |
The scene or schema back, with the plot added appropriately
This function adds a histogram to a plotscaper scene or schema.
add_histogram(x, variables = NULL, options = NULL)add_histogram(x, variables = NULL, options = NULL)
x |
A |
variables |
A vector of variable names: one continuous (required), one continuous (optional) |
options |
A list of options |
The scene or schema back, with the plot added appropriately
This function adds a 2D histogram to a plotscaper scene or schema.
add_histogram2d(x, variables = NULL, options = NULL)add_histogram2d(x, variables = NULL, options = NULL)
x |
A |
variables |
A vector of variable names: two continuous (required), one continuous (optional) |
options |
A list of options |
The scene or schema back, with the plot added appropriately
This function adds a parallel coordinates plot
to a plotscaper scene or schema.
add_pcoords(x, variables = NULL, options = NULL)add_pcoords(x, variables = NULL, options = NULL)
x |
A |
variables |
A vector of variable names: at least two continuous or discrete variables |
options |
A list of options |
The scene or schema back, with the plot added appropriately
This function adds a plot to an existing plotscaper
scene or schema. Not meant to be called directly
but instead with a wrapper function such as
add_scatterplot().
add_plot(x, spec)add_plot(x, spec)
x |
A plotscaper scene or schema |
spec |
A list with the plot specification |
The scene or schema back
This function adds a scatterplot to a plotscaper scene or schema.
add_scatterplot(x, variables = NULL, options = NULL)add_scatterplot(x, variables = NULL, options = NULL)
x |
A |
variables |
A vector of variable names: two continuous or discrete (required), one continuous (optional) |
options |
A list of options |
The scene or schema back, with the plot added appropriately
This function assigns specific cases (rows of the data)
to a permanent group within a plotscaper scene or schema.
Permanent group assignments are only removed by double-clicking.
assign_cases(x, cases = NULL, group = 1)assign_cases(x, cases = NULL, group = 1)
x |
A |
cases |
The cases (rows) to select |
group |
The group to assign the cases to (can be 1, 2, or 3) |
The scene or schema back
This function returns the cases of the data which
are assigned to a specific permanent group within
a plotscaper scene.
assigned_cases(x, group = 1)assigned_cases(x, group = 1)
x |
A |
group |
The group to retrieve the cases of (can be: 1, 2, or 3) |
A numeric vector of case ids
This function clears an existing layout. See set_layout().
clear_layout(x)clear_layout(x)
x |
A |
The scene or schema back
plotscaper schemaThis function constructs a schema of an interactive
plotscaper figure.
create_schema(data = NULL, options = NULL)create_schema(data = NULL, options = NULL)
data |
A dataframe |
options |
A list of options |
An object of class plotscaper_schema
create_schema(mtcars) |> add_scatterplot(c("wt", "mpg")) |> render()create_schema(mtcars) |> add_scatterplot(c("wt", "mpg")) |> render()
Dispatches a message to a plotscaper scene or schema
dispatch_message(x, message)dispatch_message(x, message)
x |
A plotscaper scene or schema |
message |
A list that will get converted to JSON message at appropriate time |
The scene or schema back
Return a list of plot ids from a plotscaper scene or schema
get_plot_ids(x)get_plot_ids(x)
x |
A plotscaper scene or schema |
The scene or schema back
This function returns a specific scale from a specifc plot
in a plotscaper scene.
get_scale(x, id = NULL, scale = NULL)get_scale(x, id = NULL, scale = NULL)
x |
A |
id |
A string id of the plot. See id |
scale |
A string id of the scale ( |
This function is primarily meant for internal use, however, you can
use it to learn how plotscaper implements scales. The output can look
a bit overwhelming, however, it's not too complicated once you understand
how plotscaper scales work.
Each scale has two important properties:
Domain: The space values are translated from
Codomain: The space values are translated to
For example, in a typical scatterplot, the x scale might have the range of
the data (e.g. [1, 10]) as its domain and the width of the plotting region
as its codomain (e.g. [0, 800] pixels).
The scale's job is to link the domain and codomain, such that
we can push values forward through the scale, first through the domain
and then the codomain. This is done by translating to an intermediate
range [0, 1]. For example, using the x scale above, we might first
translate the value 5.5 to 0.5 (midpoint of the domain) and then
translate 0.5 to 400 (midpoint of the codomain). We may also be able
to reverse the process and pull values back through the scale, first
through the codomain and then through the domain.
Scale, domain, and codomain each have props and defaults properties
which store the relevant values. For example, for a continuous scale,
props and defaults store the min and max as well as a transformation
function and its inverse (trans, inv), for a discrete point scale,
they store the vector of labels, their order, etc...
On scale, the props and defaults store the following properties:
zero, one, scale, mult. The zero and one properties modify where
the normalized domain values get placed in the codomain, and vice versa.
Suppose our x ([1, 10], [0, 800] px) scale had zero = 0.1 and one = 0.9.
Then data values get pushed to the following intermediate values:
The value 1 to 0.1 since 0.1 + (1 - 1) / (10 - 1) * (0.9 - 0.1) = 0.1
The value 2 to 0.1889 since 0.1 + (2 - 1) / (10 - 1) * (0.9 - 0.1) = 0.1889
The value 3 to 0.2778 since 0.1 + ((3 - 1) / (10 - 1)) * (0.9 - 0.1) = 0.2778
...
The value 10 to 0.9 since 0.1 + ((10 - 1) / (10 - 1)) * (0.9 - 0.1) = 0.9
When those values get translated to the space of the codomain, we end up with 10% margins on each side, i.e.
The value 1 gets pushed to 80 pixels
...
The value 10 gets pushed to 720 pixels
The scale and mult properties both multiply the normalized domain values.
They work the same way, however, they are different semantically: scale is
meant to be constant whereas mult may change dynamically,
through interaction. For example, by default, in a barplot, the width scale
gets assigned the scale value of 1 / k, where k is the number of
categories/bars, and a mult value of 0.9. This means that each bar is
1 / k * 0.9 * [plot width in pixels] wide, and we can dynamically make it
wider or narrower by pressing the +/- keys to modify the mult property
(but not the scale property).
A list of scale properties
A string which uniquely identifies a plot plotscaper scene or schema.
idid
An object of class NULL of length 0.
id is a string that uniquely identifies a plot within a
plotscaper scene or schema. It can match a plot
based on its position (e.g. "plot1", "plot2", ...),
in the order the plots were added, left-to-right top-to-bottom,
or it can match plot based on type (e.g. "scatter1" or "barplot3"),
again, in order of addition.
If the plot is matched based on type, the morphemes "plot" and "gram" are ignored, such that e.g. "scatterplot1" is the same as "scatter1" and "histogram2d4" is the same as "histo2d4".
The string can also be shortened, e.g. "p1" for "plot1", "s2" for "scatter2", or "hh3" for "histo2d3".
This function switches the representation of a plot to a normalized one, e.g. spineplot, spinogram, etc...
normalize(x, id = NULL)normalize(x, id = NULL)
x |
A |
id |
A string id of the plot. See id |
The scene or schema back
Used mainly for setting up the HTTP server for communication between an interactive R session and the figure.
plotscaper_globalplotscaper_global
An object of class environment of length 7.
Output and render functions for using plotscaper within Shiny applications and interactive Rmd documents.
plotscaperOutput(outputId, width = "100%", height = "400px") renderPlotscaper(expr, env = parent.frame(), quoted = FALSE)plotscaperOutput(outputId, width = "100%", height = "400px") renderPlotscaper(expr, env = parent.frame(), quoted = FALSE)
outputId |
output variable to read from |
width, height
|
Must be a valid CSS unit (like |
expr |
An expression that generates a plotscaper |
env |
The environment in which to evaluate |
quoted |
Is |
A Shiny widget output
A rendered Shiny widget
This function removes the last plot from a plotscaper
scene or schema.
pop_plot(x)pop_plot(x)
x |
A plotscaper scene or schema |
The scene or schema back
Constructs a reducer that can be used to show alternative summaries
in a plotscaper plot.
reducer(initialfn = NULL, reducefn = NULL, name = NULL)reducer(initialfn = NULL, reducefn = NULL, name = NULL)
initialfn |
An JavaScript initializing function |
reducefn |
A JavaScript reducer function specified |
name |
A name for the reducer (a string) |
reducefn and initialfn should be strings interpretable
as JavaScript functions. Further:
initialfn should take 0 arguments and just return some value (i.e. a thunk).
reducefn should take two arguments previous and next and return a result
of the same type as previous.
A reducer (which is really just a list with some additional formatting)
r <- reducer(initialfn = "() => 0", reducefn = "(x, y) => Math.max(x, y)", name = "max") create_schema(mtcars) |> add_barplot(c("cyl", "mpg"), options = list(reducer = r))r <- reducer(initialfn = "() => 0", reducefn = "(x, y) => Math.max(x, y)", name = "max") create_schema(mtcars) |> add_barplot(c("cyl", "mpg"), options = list(reducer = r))
This function removes a specific plot from a plotscaper
scene or schema.
remove_plot(x, id = NULL)remove_plot(x, id = NULL)
x |
A plotscaper scene or schema |
id |
A string id of the plot. See id |
The scene or schema back
This function takes a plotscaper schema and renders it as a
concrete htmlwidgets widget.
render( schema, launch_server = TRUE, width = NULL, height = NULL, elementId = NULL, options = NULL )render( schema, launch_server = TRUE, width = NULL, height = NULL, elementId = NULL, options = NULL )
schema |
A |
launch_server |
Whether to launch a httpuv server for interaction with figure |
width |
Width |
height |
Height |
elementId |
Id of the HTML element to render the scene in (optional) |
options |
A list of options |
An object of class plotscaper_scene
This function resets a plotscaper scene or schema.
All selection/group assignment will be removed, and
axis limits/levels of zoom will be restored to default.
reset(x)reset(x)
x |
A |
The scene or schema back
This function selects specific cases (rows of the data)
within a plotscaper scene or schema by assigning
them to transient selection.
Transient group assignment is removed by clicking.
select_cases(x, cases = NULL)select_cases(x, cases = NULL)
x |
A |
cases |
The cases (rows) to select |
The scene or schema back
This function returns the cases of the data which are selected
within a plotscaper scene.
selected_cases(x)selected_cases(x)
x |
A |
A numeric vector of case ids
This function sets a layout for a plotscaper scene. Similar to the
graphics::layout function.
set_layout(x, layout = NULL)set_layout(x, layout = NULL)
x |
A |
layout |
A numeric matrix of plot ids, arranged into contiguous rectangles |
The scene or schema back
This functions sets reactive paramaters on a plot such as a histogram.
set_parameters( x, id = NULL, width = NULL, anchor = NULL, width_x = NULL, anchor_x = NULL, width_y = NULL, anchor_y = NULL )set_parameters( x, id = NULL, width = NULL, anchor = NULL, width_x = NULL, anchor_x = NULL, width_y = NULL, anchor_y = NULL )
x |
A |
id |
A string id of the plot. See id |
width |
Histogram binwidth |
anchor |
Histogram anchor |
width_x |
2D histogram binwidth (x-axis) |
anchor_x |
2D histogram anchor (x-axis) |
width_y |
2D histogram binwidth (y-axis) |
anchor_y |
2D histogram anchor (y-axis) |
The scene or schema back
This function sets the values of a scale within one plot
inside a plotscaper scene or schema.
set_scale( x, id = NULL, scale = NULL, min = NULL, max = NULL, transformation = NULL, breaks = NULL, zero = NULL, one = NULL, direction = NULL, mult = NULL, default = NULL, unfreeze = NULL )set_scale( x, id = NULL, scale = NULL, min = NULL, max = NULL, transformation = NULL, breaks = NULL, zero = NULL, one = NULL, direction = NULL, mult = NULL, default = NULL, unfreeze = NULL )
x |
A |
id |
A string id of the plot. See id |
scale |
A string identifying scale. Can be: "x", "y", "area", or "size". |
min |
Scale minimum (continuous scales only) |
max |
Scale maximum (continuous scales only) |
transformation |
A transformation to apply ("log10" or "sqrt", continuous only) |
breaks |
A vector of discrete breaks (discrete scale only) |
zero |
The proportion of codomain to which the smallest/first value gets mapped to |
one |
The proportion of codomain to which largest/last value gets mapped to |
direction |
Scale direction. Can be |
mult |
Scale multiplier |
default |
Whether to set other arguments as scale defaults |
unfreeze |
Whether to unfreeze frozen parameters (such as the lower y-axis limit in barplot) |
The scene or schema back
plostcaper scenesThis function starts an httpuv server for an interactive communication
between the R session and plotscaper scenes.
Uses plotscaper_global options.
start_server(random_port = FALSE)start_server(random_port = FALSE)
random_port |
Whether to use a random port number. Useful if the default port is already taken. |
Nothing (called for side effects)
This function zooms into a rectangular area of the specified plot. The coordinates of the rectangular area can be specified with either percentages of the plotting region, absolute coordinates (pixels), or data coordinates.
zoom(x, id = NULL, coords = NULL, units = "pct")zoom(x, id = NULL, coords = NULL, units = "pct")
x |
A plotscaper scene or schema |
id |
A string id of the plot. See id |
coords |
The coordinates of a rectangle to
zoom into, in the following order: |
units |
The units with which to interpret the coordinates. Can be "pct" (percentages of the plotting region), "abs" (absolute screen coordinates, in pixels), or "data" (data coordinates; only works if both scales are continuous). |
The scene or schema back