babyplots-logo

abyplots

Start
JavaScript
R
Python
Creator
PowerPoint Add-in

Babyplots R Package

Babyplots is an easy to use library for creating interactive 3d graphs for exploring and presenting data.

Table of Contents


Usage

The babyplots R package can be installed from its bitbucket page using devtools:

devtools::install_bitbucket("derpylz/babyplots.git")

And loaded in your R session with:

library(babyplots)

This will expose the six plotting functions:

pointCloud()
shapeCloud()
heatMap()
surface()
imgStack()
meshStream()

as well as the corresponding Shiny bindings

# pointCloud Shiny bindings:
pointCloudOutput()
renderPointCloud()
# shapeCloud Shiny bindings:
shapeCloudOutput()
renderShapeCloud()
# heatMap Shiny bindings:
heatMapOutput()
renderHeatmap()
# surface Shiny bindings:
surfaceOutput()
renderSurface()
# imgStack Shiny bindings:
imgStackOutput()
renderImgStack()
# meshStream Shiny bindings:
meshStreamOutput()
renderMeshStream()

You can remind yourself of the arguments to the plotting functions at any time using the R manual:

?pointCloud
?shapeCloud
?heatMap
?surface
?imgStack
?meshStream

You can create a simple plot using any of the plotting functions, which directly prints the resulting visualization. Alternatively, you can assign the return value of the plotting functions to a variable. This allows you to later change some of the properties of the resulting babyplots object, as well as to add additional plots to the visualization.

# surface plot of height data
surf1 <- surface(coordMatrix, "values", as.vector(t(coordMatrix)),
                 backgroundColor = "#dfdfdf", showUI = TRUE,
                 xScale = 0.1, yScale = 0.01, zScale = 0.1)
# the same height data, but flipped
surf2 <- surface(-coordMatrix, "values", as.vector(t(coordMatrix)), showLegend = FALSE)

surf1 + surf2

The following sections explain the plotting functions and the babyplots object in detail.


Plot types

The following six plot types are currently available in the babyplots package. Each plotting function returns a babyplots object, which when printed into the console shows the visualization.

Point cloud

Point clouds are 3 dimensional scatter plots, where three variables (x, y and z) define the position of points in the coordinate system. One additional variable can be visualized by the color of the points.

The pointCloud() plotting function takes the following arguments:

Argument Type Default Description
coords matrix required 3 column matrix with x, y and z coordinates.
colorBy character required Controls how the colorVar values are interpreted. Either "categories" for discrete values, "values" for continuous values, or "direct" when colorVar is a vector of colors in hex format (e.g. "#e95420").
colorVar character or numerical vector required Color variable for the data points, containing category names, numerical values, or hex color strings, depending on the colorBy parameter.
name character "point cloud" Name of the plot for displaying it in a plot shape legend.
size double 1 Point size
width integer NULL Width of the widget, fits to the viewer pane when left empty.
height integer NULL Height of the widget, fits to the viewer pane when left empty.
xScale double 1 Scale x axis by a factor.
yScale double 1 Scale y axis by a factor
zScale double 1 Scale z axis by a factor
colorScale character NULL Name of a colorbrewer scale (e.g. "OrRd"), "Viridis", or "custom". If set to "custom", the customColorScale parameter is also needed.
customColorScale character vector NULL Character vector of at least 2 colors. Only needed if colorScale is set to "custom".
backgroundColor character "#ffffffff" Color of background as hex color string.
showLegend logical TRUE Display legend for categories of values.
showShape logical FALSE Add this plot to the legend of plot shapes.
fontSize double 11 Size of legend text.
fontColor character "black" Color of legend text. As a valid html color (e.g. "black" or "#000000").
legendTitle character "" Title for the legend
legendTitleFontSize double 16 Size of the legend title font.
legendTitleFontColor character "black" Color of the legend title font.
showAxes logical or list FALSE Display plot axes. Either one logical, or a list of three logicals, one for each axis (x, y, z).
axisLabels list list("X", "Y", "Z") List of labels for the axes.
axisColors character or list "#666666" Colors for the axes and their labels. Either one hex string (e.g. #000000), or a list of three hex strings, one for each axis (x, y, z).
tickBreaks double or list 2 Interval of ticks on axes. Either one numerical value, or a list of three numbers, one for each axis (x, y, z).
showTickLines logical, list or list of lists FALSE Display lines at tick intervals along axes. Either one logical, a list of three logicals, one for each axis (x, y, z), or a list of three lists with two logicals each, for each axis plane ([xy, xz], [yx, yz], [zx, zy]).
tickLineColors character, list or list of lists "#aaaaaa" Colors for the tick lines. Either one hex string (e.g. #000000), a list of three strings, one for each axis (x, y, z), or a list of three lists with two strings, for each axis plane ([xy, xz], [yx, yz], [zx, zy]).
hasAnimation logical FALSE Show animation of 2D to 3D pointcloud.
animationTargets matrix NULL A 2D embedding of the 3D data to be used for the unfolding animation. 2 column matrix.
animationDelay integer 100 Number of frames before animation from 2D to 3D is started.
animationDuration integer 200 Number of frames for transitioning between 2D and 3D.
animationLoop logical FALSE Loop the animation (forwards and reverse).
turntable logical FALSE Rotate the camera around the plot.
rotationRate double 0.01 Speed of turntable rotation. A positive value rotates the camera counter clockwise, a negative value clockwise.
shapeLegendTitle character "" Title for the plot shape legend.
showUI logical FALSE Display buttons on the visualization. These buttons make it possible to add labels to the plot, or to export the plot as a JSON file.

Shape cloud

Shape clouds are 3 dimensional scatter plots, where three variables (x, y and z) define the position of 3-dimensional shapes in the coordinate system. One additional variable can be visualized by the color of the points.

Available shapes are:

All data points of one shapeCloud plot have the same shape. You can combine multiple shape plots with different shapes. If legendShowShape is set to TRUE, the plot will be listed in a separate legend, with its name and shape.

Additionally, each data point can have an information string assigned to it that is displayed when the corresponding shape in the plot is clicked. These strings can include line breaks ("\n").

The shapeCloud() plotting function takes the following arguments:

Argument Type Default Description
coords matrix required 3 column matrix with x, y and z coordinates.
colorBy character required Controls how the colorVar values are interpreted. Either "categories" for discrete values, "values" for continuous values, or "direct" when colorVar is a vector of colors in hex format (e.g. "#e95420").
colorVar character or numerical vector required Color variable for the data points, containing category names, numerical values, or hex color strings, depending on the colorBy parameter.
name character "shape cloud" Name of the plot for displaying it in a plot shape legend.
shape character "box" Shape of the data points in the plot. One of c("box", "sphere", "torus", "cone", "cylinder").
size double 1 Point size
width integer NULL Width of the widget, fits to the viewer pane when left empty.
height integer NULL Height of the widget, fits to the viewer pane when left empty.
xScale double 1 Scale x axis by a factor.
yScale double 1 Scale y axis by a factor
zScale double 1 Scale z axis by a factor
colorScale character NULL Name of a colorbrewer scale (e.g. "OrRd"), "Viridis", or "custom". If set to "custom", the customColorScale parameter is also needed.
customColorScale character vector NULL Character vector of at least 2 colors. Only needed if colorScale is set to "custom".
backgroundColor character "#ffffffff" Color of background as hex color string.
showLegend logical TRUE Display legend for categories of values.
showShape logical TRUE Add this plot to the legend of plot shapes.
fontSize double 11 Size of legend text.
fontColor character "black" Color of legend text. As a valid html color (e.g. "black" or "#000000").
legendTitle character "" Title for the legend
legendTitleFontSize double 16 Size of the legend title font.
legendTitleFontColor character "black" Color of the legend title font.
showAxes logical or list FALSE Display plot axes. Either one logical, or a list of three logicals, one for each axis (x, y, z).
axisLabels list list("X", "Y", "Z") List of labels for the axes.
axisColors character or list "#666666" Colors for the axes and their labels. Either one hex string (e.g. #000000), or a list of three hex strings, one for each axis (x, y, z).
tickBreaks double or list 2 Interval of ticks on axes. Either one numerical value, or a list of three numbers, one for each axis (x, y, z).
showTickLines logical, list or list of lists FALSE Display lines at tick intervals along axes. Either one logical, a list of three logicals, one for each axis (x, y, z), or a list of three lists with two logicals each, for each axis plane ([xy, xz], [yx, yz], [zx, zy]).
tickLineColors character, list or list of lists "#aaaaaa" Colors for the tick lines. Either one hex string (e.g. #000000), a list of three strings, one for each axis (x, y, z), or a list of three lists with two strings, for each axis plane ([xy, xz], [yx, yz], [zx, zy]).
folded logical FALSE Show animation of 2D to 3D pointcloud.
foldedEmbedding matrix NULL A 2D embedding of the 3D data to be used for the unfolding animation. 2 column matrix.
foldAnimDelay integer 100 Number of frames before animation from 2D to 3D is started.
foldAnimDuration integer 200 Number of frames for transitioning between 2D and 3D.
dpInfo character vector NULL Vector with information to be displayed for each data point on click.
turntable logical FALSE Rotate the camera around the plot.
rotationRate double 0.01 Speed of turntable rotation. A positive value rotates the camera counter clockwise, a negative value clockwise.
shapeLegendTitle character "" Title for the plot shape legend.
showUI logical FALSE Display buttons on the visualization. These buttons make it possible to add labels to the plot, or to export the plot as a JSON file.

Surface

The surface plot creates a 3 dimensional surface that is defined by a height variable for each point on a x-y plane given by the rows and columns of a 2d matrix. An additional variable can be visualized by the color of the surface points. The color is interpolated between the defined points of the surface.

The surface() plotting function takes the following arguments:

Argument Type Default Description
coords matrix required 2-dimensional matrix with height data.
colorBy character required Controls how the colorVar values are interpreted. Either "categories" for discrete values, "values" for continuous values, or "direct" when colorVar is a vector of colors in hex format (e.g. "#e95420").
colorVar character or numerical vector required Color variable for the data points, containing category names, numerical values, or hex color strings, depending on the colorBy parameter.
name character "shape cloud" Name of the plot for displaying it in a plot shape legend.
width integer NULL Width of the widget, fits to the viewer pane when left empty.
height integer NULL Height of the widget, fits to the viewer pane when left empty.
xScale double 1 Scale x axis by a factor.
yScale double 1 Scale y axis by a factor
zScale double 1 Scale z axis by a factor
colorScale character NULL Name of a colorbrewer scale (e.g. "OrRd"), "Viridis", or "custom". If set to "custom", the customColorScale parameter is also needed.
customColorScale character vector NULL Character vector of at least 2 colors. Only needed if colorScale is set to "custom".
backgroundColor character "#ffffffff" Color of background as hex color string.
showLegend logical TRUE Display legend for categories of values.
showShape logical FALSE Add this plot to the legend of plot shapes.
fontSize double 11 Size of legend text.
fontColor character "black" Color of legend text. As a valid html color (e.g. "black" or "#000000").
legendTitle character "" Title for the legend
legendTitleFontSize double 16 Size of the legend title font.
legendTitleFontColor character "black" Color of the legend title font.
showAxes logical or list FALSE Display plot axes. Either one logical, or a list of three logicals, one for each axis (x, y, z).
axisLabels list list("X", "Y", "Z") List of labels for the axes.
axisColors character or list "#666666" Colors for the axes and their labels. Either one hex string (e.g. #000000), or a list of three hex strings, one for each axis (x, y, z).
tickBreaks double or list 2 Interval of ticks on axes. Either one numerical value, or a list of three numbers, one for each axis (x, y, z).
showTickLines logical, list or list of lists FALSE Display lines at tick intervals along axes. Either one logical, a list of three logicals, one for each axis (x, y, z), or a list of three lists with two logicals each, for each axis plane ([xy, xz], [yx, yz], [zx, zy]).
tickLineColors character, list or list of lists "#aaaaaa" Colors for the tick lines. Either one hex string (e.g. #000000), a list of three strings, one for each axis (x, y, z), or a list of three lists with two strings, for each axis plane ([xy, xz], [yx, yz], [zx, zy]).
turntable logical FALSE Rotate the camera around the plot.
rotationRate double 0.01 Speed of turntable rotation. A positive value rotates the camera counter clockwise, a negative value clockwise.
shapeLegendTitle character "" Title for the plot shape legend.
showUI logical FALSE Display buttons on the visualization. These buttons make it possible to add labels to the plot, or to export the plot as a JSON file.

Heat map

The heat map is a 3 dimensional bar chart defined similarly to the surface plot, where the height of each bar on a x-y plane is given by the value in a row-column pair of a 2d matrix. An additional variable can be visualized by the color of the bar.

The heatMap() plotting function takes the following arguments:

Argument Type Default Description
coords matrix required 2-dimensional matrix with height data.
colorBy character required Controls how the colorVar values are interpreted. Either "categories" for discrete values, "values" for continuous values, or "direct" when colorVar is a vector of colors in hex format (e.g. "#e95420").
colorVar character or numerical vector required Color variable for the data points, containing category names, numerical values, or hex color strings, depending on the colorBy parameter.
name character "shape cloud" Name of the plot for displaying it in a plot shape legend.
size double 1 Controls the width in the x and z dimensions of the pillars. Values should be between 0 and 1, values over 1 cause the pillars to intersect each other.
width integer NULL Width of the widget, fits to the viewer pane when left empty.
height integer NULL Height of the widget, fits to the viewer pane when left empty.
xScale double 1 Scale x axis by a factor.
yScale double 1 Scale y axis by a factor
zScale double 1 Scale z axis by a factor
colorScale character NULL Name of a colorbrewer scale (e.g. "OrRd"), "Viridis", or "custom". If set to "custom", the customColorScale parameter is also needed.
customColorScale character vector NULL Character vector of at least 2 colors. Only needed if colorScale is set to "custom".
backgroundColor character "#ffffffff" Color of background as hex color string.
showLegend logical TRUE Display legend for categories of values.
showShape logical FALSE Add this plot to the legend of plot shapes.
fontSize double 11 Size of legend text.
fontColor character "black" Color of legend text. As a valid html color (e.g. "black" or "#000000").
legendTitle character "" Title for the legend
legendTitleFontSize double 16 Size of the legend title font.
legendTitleFontColor character "black" Color of the legend title font.
showAxes logical or list FALSE Display plot axes. Either one logical, or a list of three logicals, one for each axis (x, y, z).
axisLabels list list("X", "Y", "Z") List of labels for the axes.
axisColors character or list "#666666" Colors for the axes and their labels. Either one hex string (e.g. #000000), or a list of three hex strings, one for each axis (x, y, z).
tickBreaks double or list 2 Interval of ticks on axes. Either one numerical value, or a list of three numbers, one for each axis (x, y, z).
showTickLines logical, list or list of lists FALSE Display lines at tick intervals along axes. Either one logical, a list of three logicals, one for each axis (x, y, z), or a list of three lists with two logicals each, for each axis plane ([xy, xz], [yx, yz], [zx, zy]).
tickLineColors character, list or list of lists "#aaaaaa" Colors for the tick lines. Either one hex string (e.g. #000000), a list of three strings, one for each axis (x, y, z), or a list of three lists with two strings, for each axis plane ([xy, xz], [yx, yz], [zx, zy]).
folded logical FALSE Show animation of 2D to 3D pointcloud.
foldedEmbedding matrix NULL A 2D embedding of the 3D data to be used for the unfolding animation. 2 column matrix.
foldAnimDelay integer 100 Number of frames before animation from 2D to 3D is started.
foldAnimDuration integer 200 Number of frames for transitioning between 2D and 3D.
turntable logical FALSE Rotate the camera around the plot.
rotationRate double 0.01 Speed of turntable rotation. A positive value rotates the camera counter clockwise, a negative value clockwise.
shapeLegendTitle character "" Title for the plot shape legend.
showUI logical FALSE Display buttons on the visualization. These buttons make it possible to add labels to the plot, or to export the plot as a JSON file.

Image stack

The image stack visualizes a set of 2 dimensional slices with pixel values. The input is a tiff stack with rgb channels. It was created and optimized for fluorescent microscopy z-stack data and therefore works best with black background and bright signal.

The imgStack() plotting function takes the following arguments:

Argument Type Default Description
img character required Path to RGB tiff image stack.
size double 1 Point size
threshold double or list 0.1 Intensity threshold for backround removal. Either one number (between 0 and 1) or list of numbers with threshold for each channel. (default 0.1).
width integer NULL Width of the widget, fits to the viewer pane when left empty.
height integer NULL Height of the widget, fits to the viewer pane when left empty.
xScale double 1 Scale x axis by a factor.
yScale double 1 Scale y axis by a factor
zScale double 1 Scale z axis by a factor
backgroundColor character "#ffffffff" Color of background as hex color string.
intensityMode character "alpha" Representation of pixel intensity, either "none", "alpha" or "mix". The default "alpha" generally looks best, but might be slightly slower than the other two options.
channelColors list list("#ff0000", "#00ff00", "#0000ff") Set the colors for each of the channels, the default is for RGB images.
channelOpacities list list(1, 1, 1) Set an overall opacity for each channel (default: list(1, 1, 1)). Only works together with intensityMode "alpha".
showAxes logical or list FALSE Display plot axes. Either one logical, or a list of three logicals, one for each axis (x, y, z).
axisLabels list list("X", "Y", "Z") List of labels for the axes.
axisColors character or list "#666666" Colors for the axes and their labels. Either one hex string (e.g. #000000), or a list of three hex strings, one for each axis (x, y, z).
tickBreaks double or list 2 Interval of ticks on axes. Either one numerical value, or a list of three numbers, one for each axis (x, y, z).
showTickLines logical, list or list of lists FALSE Display lines at tick intervals along axes. Either one logical, a list of three logicals, one for each axis (x, y, z), or a list of three lists with two logicals each, for each axis plane ([xy, xz], [yx, yz], [zx, zy]).
tickLineColors character, list or list of lists "#aaaaaa" Colors for the tick lines. Either one hex string (e.g. #000000), a list of three strings, one for each axis (x, y, z), or a list of three lists with two strings, for each axis plane ([xy, xz], [yx, yz], [zx, zy]).
turntable logical FALSE Rotate the camera around the plot.
rotationRate double 0.01 Speed of turntable rotation. A positive value rotates the camera counter clockwise, a negative value clockwise.
showUI logical FALSE Display buttons on the visualization. These buttons make it possible to add labels to the plot, or to export the plot as a JSON file.

The babyplots object

All plotting functions create a babyplots object. When printed to the console, this object shows the visualization. Assigning it to a variable allows you to change parameters of the visualization after its creation using the $ selector. The babyplots object has the following slots:

Slot Type Description
plots list A list of all plots that have been added to this babyplots object. The plots themselves are named lists, so their parameters that were set at the creation can also be accessed and changed through this slot.
turntable logical Controls the camera rotation around the plot
rotationRate double The speed at which the camera rotates around the plot, if turntable is set to TRUE
shapeLegendTitle character "" Title for the plot shape legend.
showUI logical Display buttons on the visualization.
backgroundColor character Color of background as hex color string.
xScale double Scale x axis by a factor.
yScale double Scale y axis by a factor
zScale double Scale z axis by a factor

Adding a two babyplots objects together creates a new babyplots object that contains both plots in the $plot slot. The general options (e.g. turntable, showUI, ...) are carried over from the first babyplots object.