plot_ly {plotly} | R Documentation

## Initiate a plotly visualization

### Description

This function maps R objects to plotly.js, an (MIT licensed) web-based interactive charting library. It provides abstractions for doing common things (e.g. mapping data values to fill colors (via `color`) or creating animations (via `frame`)) and sets some different defaults to make the interface feel more 'R-like' (i.e., closer to `plot()` and `ggplot2::qplot()`).

### Usage

    plot_ly(data = data.frame(), ..., type = NULL, name, color, colors = NULL,
      alpha = NULL, stroke, strokes = NULL, alpha_stroke = 1, size,
      sizes = c(10, 100), span, spans = c(1, 20), symbol, symbols = NULL,
      linetype, linetypes = NULL, split, frame, width = NULL, height = NULL,
      source = "A")

### Arguments

`data` | A data frame (optional) or crosstalk::SharedData object.
`...` | Arguments (i.e., attributes) passed along to the trace `type`. See `schema()` for a list of acceptable attributes for a given trace `type` (by going to `traces` -> `type` -> `attributes`). Note that attributes provided at this level may override other arguments (e.g. `plot_ly(x = 1:10, y = 1:10, color = I("red"), marker = list(color = "blue"))`).
`type` | A character string specifying the trace type (e.g. `"scatter"`, `"bar"`, `"box"`, etc). If specified, it always creates a trace, otherwise
`name` | Values mapped to the trace's name attribute. Since a trace can only have one name, this argument acts very much like `split` in that it creates one trace for every unique value.
`color` | Values mapped to relevant 'fill-color' attribute(s) (e.g. fillcolor, marker.color, textfont.color, etc.). The mapping from data values to color codes may be controlled using `colors` and `alpha`, or avoided altogether via `I()` (e.g., `color = I("red")`). Any color understood by `grDevices::col2rgb()` may be used in this way.
`colors` | Either a colorbrewer2.org palette name (e.g. "YlOrRd" or "Blues"), or a vector of colors to interpolate in hexadecimal "#RRGGBB" format, or a color interpolation function like `colorRamp()`.
`alpha` | A number between 0 and 1 specifying the alpha channel applied to `color`. Defaults to 0.5 when mapping to fillcolor and 1 otherwise.
`stroke` | Similar to `color`, but values are mapped to relevant 'stroke-color' attribute(s) (e.g., marker.line.color and line.color for filled polygons). If not specified, `stroke` inherits from `color`.
`strokes` | Similar to `colors`, but controls the `stroke` mapping.
`alpha_stroke` | Similar to `alpha`, but applied to `stroke`.
`size` | (Numeric) values mapped to relevant 'fill-size' attribute(s) (e.g., marker.size, textfont.size, and error_x.width). The mapping from data values to symbols may be controlled using `sizes`, or avoided altogether via `I()` (e.g., `size = I(30)`).
`sizes` | A numeric vector of length 2 used to scale `size` to pixels.
`span` | (Numeric) values mapped to relevant 'stroke-size' attribute(s) (e.g., marker.line.width, line.width for filled polygons, and error_x.thickness) The mapping from data values to symbols may be controlled using `spans`, or avoided altogether via `I()` (e.g., `span = I(30)`).
`spans` | A numeric vector of length 2 used to scale `span` to pixels.
`symbol` | (Discrete) values mapped to marker.symbol. The mapping from data values to symbols may be controlled using `symbols`, or avoided altogether via `I()` (e.g., `symbol = I("pentagon")`). Any pch value or symbol name may be used in this way.
`symbols` | A character vector of pch values or symbol names.
`linetype` | (Discrete) values mapped to line.dash. The mapping from data values to symbols may be controlled using `linetypes`, or avoided altogether via `I()` (e.g., `linetype = I("dash")`). Any `lty` (see par) value or dash name may be used in this way.
`linetypes` | A character vector of `lty` values or dash names
`split` | (Discrete) values used to create multiple traces (one trace per value).
`frame` | (Discrete) values used to create animation frames.
`width` | Width in pixels (optional, defaults to automatic sizing).
`height` | Height in pixels (optional, defaults to automatic sizing).
`source` | a character string of length 1. Match the value of this string with the source argument in `event_data()` to retrieve the event data corresponding to a specific plot (shiny apps can have multiple plots).

### Details

Unless `type` is specified, this function just initiates a plotly object with 'global' attributes that are passed onto downstream uses of `add_trace()` (or similar). A formula must always be used when referencing column name(s) in `data` (e.g. `plot_ly(mtcars, x = ~wt)`). Formulas are optional when supplying values directly, but they do help inform default axis/scale titles (e.g., `plot_ly(x = mtcars$wt)` vs `plot_ly(x = ~mtcars$wt)`)

### Author(s)

Carson Sievert

### References

https://plotly-book.cpsievert.me/the-plotly-cookbook.html

### See Also

- For initializing a plotly-geo object: `plot_geo()`

- For initializing a plotly-mapbox object: `plot_mapbox()`

- For translating a ggplot2 object to a plotly object: `ggplotly()`

- For modifying any plotly object: `layout()`, `add_trace()`, `style()`

- For linked brushing: `highlight()`

- For arranging multiple plots: `subplot()`, `crosstalk::bscols()`

- For inspecting plotly objects: `plotly_json()`

- For quick, accurate, and searchable plotly.js reference: `schema()`

### Examples

    ## Not run:

    # plot_ly() tries to create a sensible plot based on the information you
    # give it. If you don't provide a trace type, plot_ly() will infer one.
    plot_ly(economics, x = ~pop)
    plot_ly(economics, x = ~date, y = ~pop)
    # plot_ly() doesn't require data frame(s), which allows one to take
    # advantage of trace type(s) designed specifically for numeric matrices
    plot_ly(z = ~volcano)
    plot_ly(z = ~volcano, type = "surface")

    # plotly has a functional interface: every plotly function takes a plotly
    # object as it's first input argument and returns a modified plotly object
    add_lines(plot_ly(economics, x = ~date, y = ~unemploy/pop))

    # To make code more readable, plotly imports the pipe operator from magrittr
    economics %>% plot_ly(x = ~date, y = ~unemploy/pop) %>% add_lines()

    # Attributes defined via plot_ly() set 'global' attributes that
    # are carried onto subsequent traces, but those may be over-written
    plot_ly(economics, x = ~date, color = I("black")) %>%
     add_lines(y = ~uempmed) %>%
     add_lines(y = ~psavert, color = I("red"))

    # Attributes are documented in the figure reference -> https://plot.ly/r/reference
    # You might notice plot_ly() has named arguments that aren't in this figure
    # reference. These arguments make it easier to map abstract data values to
    # visual attributes.
    p <- plot_ly(iris, x = ~Sepal.Width, y = ~Sepal.Length)
    add_markers(p, color = ~Petal.Length, size = ~Petal.Length)
    add_markers(p, color = ~Species)
    add_markers(p, color = ~Species, colors = "Set1")
    add_markers(p, symbol = ~Species)
    add_paths(p, linetype = ~Species)

    ## End(Not run)

[Package plotly version 4.8.0 Index]