In gvarunkumar/plotly: Create Interactive Web Graphics via 'plotly.js'

knitr::opts_chunk$set(
  message = FALSE, 
  warning = FALSE, 
  fig.width = 7, 
  fig.height = 3
)

This vignette outlines the philosophy behind plot_ly() through a series of examples (click on the static images to see the interactive version). In a nutshell, plot_ly() aims to:

1. Provide sensible defaults/messages/warnings based on the information supplied, but still allows for full customization through plotly.js' (the open source JavaScript graphing library which powers plotly) figure reference.
2. Leverage useful concepts from the grammar of graphics (without requiring it to be used).

Smart defaults, messages, warnings, errors

If no visualization type is specified, plot_ly() infers a sensible type based on the information provided. In this case, a numeric matrix (named volcano) is mapped to the z attribute, so a heatmap is a sensible default.

library(plotly)
str(volcano)
plot_ly(z = ~volcano)

A heatmap is not the only way to visualize a numeric matrix. Since plot_ly() only initializes a plotly object,

we can change the default visualization type using any of the add_*() functions:

add_surface(plot_ly(z = ~volcano))

There are a number of add_*() functions, for a number

Functional interface

Plotly's R package has a functional interface: every function takes a plotly object as it's first input argument and returns a modified plotly object. To make code more readable, plotly re-exports the pipe operator (%>%) from the magrittr package. The pipe operator takes the object on the left-hand side and injects it into the first argument (by default) of the function on the right-hand side. This allows us to read code from left to right instead of inside out.

# these two lines of code are equivalent, but the second is easier to read
plotly_POST(add_surface(plot_ly(z = ~volcano)))
plot_ly(z = ~volcano) %>% add_surface() %>% plotly_POST()

plot_ly(diamonds, x = ~cut)
plot_ly(diamonds, y = ~cut)

To create a plotly visualization, start with plot_ly().

library(plotly)
plot_ly(economics, x = ~date, y = ~unemploy / pop)

A plotly visualization is composed of one (or more) trace(s), and every trace has a type (the default type is 'scatter'). The arguments/properties that a trace will respect (documented here) depend on it's type. A scatter trace respects mode, which can be any combination of "lines", "markers", "text" joined with a "+":

library(plotly)
plot_ly(economics, x = ~date, y = ~unemploy / pop, 
        type = "scatter", mode = "markers+lines")

You can manually add a trace to an existing plot with add_trace(). In that case, you'll want to either name your traces, or hide the legend by setting showlegend = FALSE

m <- loess(unemploy / pop ~ as.numeric(date), data = economics)
p <- plot_ly(economics, x = ~date, y = ~unemploy / pop, name = "raw") 
add_lines(p, y = ~fitted(m), name = "loess")

plotly was designed with a pure, predictable, and pipeable interface in mind, so you can also use the %>% operator to create a visualization pipeline:

economics %>%
  plot_ly(x = ~date, y = ~unemploy / pop) %>% 
  add_lines(y = ~fitted(m)) %>%
  layout(showlegend = F)

TODO: talk about dplyr verbs!

library(dplyr)
economics %>%
  mutate(rate = unemploy / pop) %>%
  plot_ly(x = ~date, y = ~rate) %>% 
  filter(rate == max(rate)) %>%
  layout(
    showlegend = F, 
    annotations = list(x = ~date, y = ~rate, text = "Peak", showarrow = T)
  )

Although these functions output special "plotly data frames", plot_ly() doesn't require a data frame for input. This makes chart types that accept a z argument especially easy to use if you have a numeric matrix:

s <- plot_ly(z = volcano, type = "surface")

If you have a free plotly account, plotly_POST() makes it easy to host/share any plotly figure (click on the image below to see the interactive version).

plotly_POST(s)

Special arguments

The plotly function arguments used thus far are documented in the figure reference, but there are a handful of additional arguments not described in the reference that make common visualizations a bit easier. These arguments are very much inspired by the semantics of ggplot2's qplot() in the sense that a scales are automatically applied these variables.

The color argument

Qualitative color mappings

If a ordinal variable (aka a non-ordered factor variable) is assigned to color, then a qualitative color palette is used by default.

plot_ly(iris, x = ~Petal.Length, y = ~Petal.Width, 
        color = ~Species, mode = "markers")

If you want to change the default palette, it's recommended that you provide a http://colorbrewer2.org qualitative pallette name (e.g., "Set1" or "Accent") to the colors argument.

plot_ly(iris, x = ~Petal.Length, y = ~Petal.Width, 
        color = ~Species, colors = "Set1", mode = "markers")

In this case, the palette consists of 9 colors and the default behavior is to pick colors that are furthest apart ("#E41A1C", "#FF7F00", and "#999999").

cols <- RColorBrewer::brewer.pal(9, "Set1")
scales::show_col(cols)

If you'd like more control over the mapping, you can provide a vector of colors (of appropriate length).

cols <- RColorBrewer::brewer.pal(nlevels(iris$Species), "Set1")
plot_ly(iris, x = ~Petal.Length, y = ~Petal.Width, 
        color = ~Species, colors = cols, mode = "markers")

Sequential color mappings

If either a numeric or an ordered factor is mapped to color, plot_ly() applies a sequential color scale by default.

plot_ly(iris, x = ~Petal.Length, y = ~Petal.Width, 
        color = ~as.ordered(Species), mode = "markers")

In the case of continuous numeric variables, plot_ly() performs a linear mapping between the data and an interpolated color pallette.

plot_ly(iris, x = ~Petal.Length, y = ~Petal.Width, 
        color = ~Sepal.Length, mode = "markers")

The colors argument takes arbitrary color codes of arbitrary length. Here is how we could use it to replicate the default mapping in ggplot2.

plot_ly(iris, x = ~Petal.Length, y = ~Petal.Width, 
        color = ~Sepal.Length, colors = c("#132B43", "#56B1F7"), 
        mode = "markers")

Diverging color mappings

To obtain a diverging color mapping, just provide a diverging palette to the colors argument.

plot_ly(iris, x = ~Petal.Length, y = ~Petal.Width, 
        color = ~Sepal.Length, colors = "PuOr", mode = "markers")

The symbol argument

To encode values using symbols, use the symbol argument.

plot_ly(iris, x = ~Petal.Length, y = ~Petal.Width, 
        symbol = ~Species, mode = "markers")

To change the default symbols used, use the symbols argument. All the valid symbol types are listed here.

plot_ly(iris, x = ~Petal.Length, y = ~Petal.Width, mode = "markers",
        symbol = ~Species, symbols = c("cross", "square", "triangle-down"))

gvarunkumar/plotly documentation built on May 17, 2019, 9:29 a.m.